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This is the firmware reference manual for the Apple® IIG5™ computer. It is for 
hardware designers and programmers who warn to work with the system firmware in 
lieu of using the Apple LIGS Toolbox routines to accomplish similar goals. 



About this manual 

: art of the Apple TIGS technical suite, of manuals, the Apple IIGS Firmware 
Reference covers the design and function of the firmware that drives the Apple IIGS. It 
provides information about the entry points for the firmware and describes the 
firmware functions and limitations, 

* Afttffe None of the manuals in the technical suite stands alone. Other manuals in the 

: describe various tools to accomplish tasks that the firmware can also perform. 
You should become familiar with the contents of the other Apple IIGS manuals 
because for most applications, you may not need to directly use the firmware, 

The audience for this manual includes programmers who want to work with the 
firmware and application programmers who wish to convert or upgrade existing 
applications for the Apple II, n Plus, He, or Ik to take advantage of the new functions 
available on the Apple IIGS. 

♦ Note: Applications written explicitly for tile Apple lie can be booted on the 
Apple IIGS, with no discernible difference in their operation. 

This manual does not incorporate any descriptions of hardware; sec the Apple 17GS 
Hardware Reference for this information. 
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What this manual contains 

Chapter 1, "Overview." provides an overview of the Apple IIGS firmware. 

Chapter 2, "Notes for Programmers, " provides information for those who are already 
familiar with other Apple I( computers. 

Chapter 3, 'System Monitor Firmware," shows how io use the system Monitor [0 
examine and change memory or registers and Lo write and debug small machine 
language programs. 

Chapter 4, "Video Firmware," describes the text input and output facilities of the 
Apple Has. 

Chapter 5, "Serial-Fort Firmware," describes Lhe features and functions of the built-in 
serial port. 

Chapter 6 r "Disk II Support," describes [he firmware support for the Apple Disk U® 
product 

Chapter 7, "SmartPort Firmware,,'' defines and describes the SmartPon Firmware as 
implemented on the Apple JIGS. 

Chapter 8, "Interru pit-Handler Firmware," describes in delail the method by which 
various kinds of interrupts are processed. 

Chapter 9, "Apple DeskTop Bus Microcontroller," describes the firmware portion of 
the Apple DeskTop Bus™. For a complete picture of this subsystem, you need this 
manual, the Apple IKS Hardware Reference, and the Apple lias Toolbox Reference. 

Chapter 10, "Mouse Firmware," describes the Apple IIGS mouse interface. 

Appendix A contains a roadmap to the Apple IIGS technical manuals. Read this 
appendix to determine which books you need to learn more about a programming 
language, the Apple IIGS hardware, or some other aspect of the Apple Hgs computer. 

Appendix B contains a list of the firmware ID bytes. The information lets you 
determine which machine in the Apple II family is running your program. By 
examining these ID bytes, you can allow your program to take advantage of the (features 
available on a particular member of this family. 

Appendix C describes die firmware entry points for the Apple IIGS, as well as the side 
effects of each routine, 

Appendix D describes the Firmware vectors. By jumping to vectors instead of directly 
to particular Firmware routines, you can maintain compatibility between your program 
and future releases of the Apple IIGS firmware. 

Appendix E describes the soft switches that control various aspects of system 
behavior. These switch locations and contents are provided for reference only. The 
contents of die switches should be modified only by system tools. 
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Appendix F lists the disasscmbler/mini-assembler opcodes. These will be useful lo the 
machine-language programmer who uses ihe system Monitor to enter small programs 
for quick tests. 

Appendix G describes the Control Panel options and deFaulis. 

Appendix H describes the contents of memory banks $E0 and $E1 

A glossary follows the appendixes. 
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Chapter 1 



Overview 



This chapter gives a brief overview of ihe Apple ncs firmware and how it relates lo the 
rest of the system software, The Apple I1GS firmware is composed of various routines 
thai are stored in the system's read-only memory (ROM). The Apple 1IGS firmware 
routines provide the means to adapt and control the Apple II GS system. 

Routines for the following Apple IIGS firmware are covered in this manual: 
system Monitor firmware 
leo firmware (I/O routines) 
c serial-port firmware Cfor character-at-a-time I/O) 
l Disk IT support (slot 6 support) 

artPort firmware (for block device I/O) 
□ inlermpl -handler firmware 
d Apple DeskTop Bus (ADB) microcontroller 
D mouse firmware 



A word about other Apple IIGS firmware 

Not all Apple IIGS firmware is discussed in this manual. The Apple IIGS ROM contains 
other fkmware, important enough to warrant separate manuals: the Apple lies 
Toolbox Cdescribed in detail in the Apple ncs Toolbox Reference), Applesoft BASIC 
(described in the Applesoft BASIC Reference}, and the AppleTalk® Personal Network 
(described in Inside AppleTalk). 



Apple IIGS Toolbox 

The Apple IIGS Toolbox provides a means of easily constructing application programs 
without necessarily using the firmware routines described in this manual. Programs 
that you construct using die tools will conform to the Apple Human Interface 
Guidelines. By offering a common set of routines that every application can call to 
implement the user interface, the tools not only ensure familiarity and consistency for 
the user but also help to reduce the application's code size and development time, 



Applesoft BASIC 

The Apple IIGS also has Applesoft BASIC in ROM so that you can create and run your 
own programs in BASIC. 
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AppleTalk 

AppleTalk is a local-area network that allows communicaLion and resource sharing by 
up to 32 computers, disks, printers, modems, and other peripheral devices. 
AppleTalk consists of communication hardware and a set of communication 
protocols. This hardware/software package, together with the computers, cables and 
connectors, shared resource managers (servers), and specialized application 

vare, functions in three major configurations: as a small-area interconnecting 
system, as a tributary co a larger network, and as a peripheral bus between Apple 
computers and their dedicated peripheral devices 



Diagnostic routines 

The system diagnostic routines arc manufacturing test routines. No external entry 
points are defined for system diagnostic routines at this time. Thus, diagnostie 
routines are not documented in this manual. 



The role of firmware in the Apple IIGS system 

The firmware is that set of low-level routines that provides programmers with an 
interface to the system hardware. The firmware, in turn, controls the display, the 
mouse, serial input/output Q/Q% and disk drives. Firmware programs, such as the 
Monitor and the Control Panel, work directly with the system memory. 

Traditionally, programmers have controlled hardware directly through their 
application programs, bypassing any system firmware. The disadvantage of this 
approach is that the programmer has to do a lot more work. More important, 
bypassing the firmware increases the likelihood that the resulting program will be 
incompatible either with other programs or with future versions of the computer. By 
using the firmware interface, a programmer can maintain compatibility with current 
and future releases of the system. 

For most of the Functions thai the firmware entry points perform, there are equivalent 
functions provided in the toolbox. The toolbox routines, in addition to performing 
like runciions, also save and restore system registers when they are caEed Read 
Chapter 2, "Notes for Programmers, " for more details about system register usage. 



The role of firmware In the Apple JIgs system 



Levels of program operation 

You can think of the different levels of program operation on the Apple TIGS as a 

irehy, with a hardware layer at the bottom, firmware layers in the middle, and the 
application at the top. Figure 1-1 shows a hierarchy of command levels', in general, 
higher-level components call on lower-level ones. CThe levels are separated by lines; 
the hardware components have heavy outlines) 




Figure l-l 

Levels of program operation 



Apple IIGS firmware 

The following sections provide an overview of the Apple IIGS firmware described in 
this manual 






System Monitor firmware 

The system Monitor firmware is a set of routines that you can use to operate 
computer at the machine-language level. You can examine and change memory 
Eons, examine and change registers, call system routines, and assemble and 
disassemble machine-language programs using the system Monitor firmware 
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Video firmware 

Video firmware allows you to manipulate the screen in low-resolution mode and text 
mode through your application programs and from the keyboard. Communication 
between the keyboard and the video screen is controlled by firmware subroutines, 
escape codes, and control characters. The video firmware provides on-screen 
editing, keyboard input, output to the screen, and cursor-control facilities. 



Serial- port firmware 

The Apple IlGs serial-port firmware provides a means to allow serial communication 
with external devices, such as printers and modems. The serial-port firmware 
provides support for such options as hardware and software handshaking and 
background printing. There are two serial ports, either of which can be configured as a 
printer port or a modem port. 



Disk II support 

The Apple lies Disk 11 firmware is a disk -support subsystem. It uses a built-in Integrated 
W02 Machine (JWM) chip and accommodates Disk II (DuoDisk® or UniDisk™) drives. 
Slot 6 is the standard Disk II support slot- The firmware that communicates with the 
MM at boot time provides support for booting Disk Il-based software. Other handling 
of Disk H devices is a function of whichever disk operating system is booted. 



SmartPort firmware 

n devices are directly manipulated by slot 6 control hardware, Intelligent devices. 
by contrast, are not directly manipulated by hardware, but rather are controlled by 
software-driven command streams. Such devices are labeled intelligent devices 
because they have their own controllers, which can interpret ihese command streams. 
The SmartPort firmware is a sec of assembly-language routines that permit you 
attach one or more intelligent devices to the external disk port of the Apple IIgs 
system. Using trie SmartPort firmware, you can control these devices through 
SmartPort calls, such as Open, Close, Format, ReadBlock, and Write Block. 
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Interrupt -handler firmware 

System iniernjpts hall the execution of a program or the performance of a function or 
feature. The system contains buili-in intermpt-handler firmware, a user's interrupt- 
handler entry poinl, and a means to notify the user when an interrupt occurs. 



Apple DeskTop Bus microcontroller 

The Apple DeskTop Bus (AD 13) microcontroller is used 10 receive information from 
peripheral units attached to the Apple DeskTop Bus, The ADB microcontroller polls 
the internal keyboard, sensing key-up and key-down events as well as control keys, and 
optionally buffers keystrokes for later access by the 65C8I6. In addition, the ADB 
microcontroller acts as host for ADB peripheral devices, such as the detachable 
keyboard and mouse. The ADB microcontroller has its own buitt-in set of 
instructions, including Talk, Listen, SendReset, and Flush. 



Mouse firmware 

The Apple EOS mouse firmware supplies the communication protocol for sensing the 
current status of the mouse. The mouse firmware tracks mouse-device position data 
and button status and provides entry points For assembly-language control. 
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This chapter contains information thai will be useful to the experienced 6502 
programmer as well as someone just beginning to use the Apple IIGS computer. 

\pple IIGS has many new features not found in previous Apple computers. 
Programs written for the Apple He or the Apple He will run on the Apple IIGS, but do 
not lake advantage of these new features. 

Among the new features of the Apple IIGS is a new set of registers, pseudoregisters, and 
flags, collectively known as the environment. Before you change the environment 
for the Apple IIGS system, read the following sections, which outline these new 
features. 



Introduction to the Apple IIGS 

The Apple IIGS personal computer is a new Apple II with many high-performance 
Features. Highlights include 

D more powerful microprocessor with faster operation and larger memory 

u high-resolution EiGB video for Super Hi-Res color graphics 

□ multivoicc digital sound synthesizer 

D detached keyboard with Apple DeskTop Bus connector 

□ built-in I/O: clock, disk port, and serial ports with AppleTalk interface 

□ compatible slots and game I/O connectors 

This list includes only the main features of the Apple IIGS. For a comprehensive Hst of 
features, refer to the Technical Introduction to the Apple IIGS. 



Microprocessor features 

The microprocessor in the Apple IIGS is a 65C816, a 16-bit design based on the 6502. 
Among the features of the 65C816 are 

□ ability to emulate a 6502 8-bil microprocessor 

n 16-bit accumulator and index registers 

C3 RilDcaUtblc Ot«l<cH ililj £.<.*%J LtAltL- <CUtl C-Vl 1>4MC) 

n 24-bit internal address bus for 16-megabyte memory space 
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Microprocessor modes 

The 65C816 microprocessor can operate in two different modes: native mode, with 

its new features, and 6502 emulation mode, for running programs written for 8- 
bit Apple II computers. 

If you are using emulation mode extensively, you will be using the firmware calls 
described in this manual. If you are using native mode, you probably will want to use 
the equivalent toolbox calls instead of directly calling the firmware. The toolbox calls 
save and restore the environment for you. 

Execution speeds 

The microprocessor in ihe Apple IIGS can operate at either of two clock speeds: the 
standard Apple II speed of 1 MHz and the faster speed of 2.8 MHz. When running 
programs in RAM, the Apple IIGS uses a few dock cycles for refreshing memory, 
making the effective processing speed about 2.5 MHz. System firmware, running in 
ROM, runs al the full 2.8 MHz. 



Expanded memory 

Thanks to the 24-bit addresses of the 65CBI6, the Apple IIGS has a memory space 
lotaltng 16 megabytes. Of this total, up to 8 megabytes of memory are available for 
RAM expansion, and 1 megabyte is available for ROM expansion. For additional 
information about memory, read the Technical Introduction to the Apple lias 

The minimum memory in the Apple IIGS is 256K. Programs written for the 

Apple IIGS — that ts, programs that run the 65C816 microprocessor in native mode, 

Charaby gaining iho ability lt> *ckJ*oo ttlCttC Limn 120ft uf 'lIlCUIUI Jr Ldili USe Up tU ill 

176K of the 256k. The rest is reserved for displays and for use by the system firmware. 

The Apple IIGS also has a special card slot dedicated to memory expansion. All of the 
RAM on a memory-expansion card is available for Apple IIGS application programs 
that call the Memory Manager. Expansion memory is contiguous: Its address space 
extends without a break through all of the RAM on the card Expansion RAM on the 
Apple IIGS is not limited to use as data storage, program code can run in any part of 
RAM. 



Super Hi-Res display 

In addition to all the video display modes of the Apple lie and Apple He, the 
Apple IIGS has two new Super 1 ti-Res display modes that look much clearer than 
standard Hi-Res and Double Hi-Res. Super Hi-Res is also easier to program because it 
maps entire bytes onto the screen, instead of 7 bits, and its memory map is linear. 
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with an analog RGB video monitor, the new display modes produce high- 
quality, high-resolution color graphics. Table 2-1 lists the specifications of the two 
new graphics display modes. 

Table 2-1 

Super Hi- Res graphics modes 





Resolution 


Bfts per 
pixel 


Colors 
par line 


Colors 
on scr»»n 




Mode 


Horfe. 


Vert. 


Colors 
possible 


J20 
640 


&2C 

640 


200 
200 


4 

2 


16 
16" 


256 
256' 


4096 

4096 



■ Different pixels in 640 mode use different pans of the palette, 

♦ Ntita Pixel is short for picture element. A pixel corresponds to the smallest dot you 
can draw on the screen. 

Each dot on the Super Hi-Res screen corresponds to a pixel. Each pixel has either a 
2-bit (640 mode) or a 4-bit G20 mode} value associated with it. The pixel values select 
colors from programmable color tables called palettes. A palette coasists of 16 
entries, and each entry is a 12-bii value specifying one of 4096 possible colors. 

In 320 mode, each pixel consists of 4 bits, so it can select any one of the 16 colors in a 
palette. In 640 mode, each byte holds four 2-bit pixels. The 16 colors in the palette are 
divided into four groups of 4 colors each, and successive pixels select from successive 
groups of 4 colors. Thus, even though a given pixel in 640 mode can be one of only 4 
colors, different pixels in a line can take on any of the 16 colors in a palette. 

To further increase die number of colors available on the display, there can be as 
many as 16 different palettes in use at the same time, allowing as many as 256 different 
colors on the screen. 



Digital sound synthesizer 

In addition to the single-bit sound output found in other computers in the Apple n 
family, the Apple IIGS has a new digital sampling sound system built around a special- 
purpose synthesizer tC called the Digital Oscillator Chip, or DOC for short Using 
the DOC, the Apple IIGS can produce 15-voice music and other complex sounds 
without tying up its main processor. Refer to the Apple IIGS Hardware Reference for 
details about the sound system and the DOC. 



Detached keyboard with Apple DeskTop Bus 

The new detached keyboard includes cursor keys and a numeric keypad. The Apple 
DeskTop Bus, which supports the keyboard and the Apple mouse, can also handle 
other input devices such as joysticks and graphics tablets. 
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Built-in I/O 

like the Apple Ik, the Apple IlGS has two built-in disk pons and two serial I/O ports 
Programs can use the buHt-ln pons and peripheral cards in slots The builHo 

ApplcTalk interface uses one of the serial ports. 

The Apple IIGS also has a built-in clock-calendar with a batten,' for continuous 
operation. 



Compatible slots and game I/O connectors 

In addition to the memory-expansion slot, the Apple IIG5 has seven I/O expansion 
slots like those on the Apple lie. Most peripheral cards designed for the Apple tl Plus 
and the Apple He will work in die Apple IIGS slots. The Apple IIGS also has game I/O 
connectors for existing game hardware. 



Environment for the firmware routines 

Many useful subroutines are listed in Appendix C, "Firmware Entry Points in Bank 
$00." All of these routines have one thing in common: To use them, the processor 
must be set up to took and act exactly like a 6502 in all respects. You must therefore set 
the operating environment to cause this irans formation to happen. 



Important 

This section contains the specific details about setting and restoring trie 
environment before calling and after returning from calling the firmware routines. 
You must follow these requirements exactly, or your program will fail. 



The specific operating environment requirements for all these routines are as follows: 

U d bit = (decimal-mode bit) 

a e bit = 1 (emu la lion- mode bit) 

D register - SO00O (direct-page register) 

3 DBR register = $0G (data bank register, called B in Chapter 3) 

a PBR register = S0O (program bank register, called K in Chapter 3) 

□ S register = SOlxx (stack pointer) 

♦ Note: If you make tools calls instead of using the firmware directly, you will not have 
to worry about the operating environment. The tool calls handle the environment 
for you, 
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Setting up the system 

To correctly prepare the system for calling the firmware routines, you must lake several 
steps: 

D Save your environment. 

□ Get into bank $00; JSL (jump to subroutine long) to a routine in bank $00. 

□ Set the D register to $0000. 

□ Set the DBR to SOO. 

z Save the value of the native-mode stack pointer, and set the stack pointer to the 
value of the emulation-mode Slack pointer, 

u Select emulation mode: set the e bit to 1 . 

These steps make the 65G816 appear to be a 6502 microprocessor operating in its 
normal environment. Now you can act up the machine registers with the parameter 
required by the particular firmware routine and execute a J5R (jump to subroutine), 
These steps are explained in the sections that follow. 

Save your environment 

The environment is the complete set of machine registers and flags that your program 
uses. Besides machine registers, the environment includes such things as processor 
speed, read-only memory (ROM) bank, language-card bank, and random-access 
memory (RAM) shadowing. 

When you run the various firmware routines, the system will use the machine registers 
for its own purposes. If you depend on a particular register having a specific value 
when you finally return to your own code, then save that register's contents on your 
native-mode stack or wherever else you wish so that you can restore the register's 
contents before you return to your other program code, To determine which registers 
each firmware routine uses or affects, see Appendix C, "Firmware Entry Points in Bank 
S00.* 

Get info bonk $00 

If vim aitempt lo run the 65C816 in emulation mode in any bank other than bank $00, 
no interrupt processing can take place, You enter program bank SOO by executing a JSL 
(jump to subroutine long) to someplace in bank $00 (if you are not already there), 
where the next steps are performed. This JSL sets the program bank register (K) to SOO, 
ill i ling that part of the firmware routine requirement. If you did not save your 
environment before entering bank $00, now would be an equally good time to do so. 

Set the D register to $0000 

A 6502 expects its zero page (called the direct page for the 65CB16 when operating in 

nau've mode) to exist in the microprocessor address range of $00 to $PF, When the D 
register is set to 0, the zero page gets positioned correctly for a 6502. 
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SettheDBRfoSDO 

The DBR is the upper 8 bits of the 24-bit data address. The DBR must have a value of 

$00 for ihe firmware routines to function. 



Sove the value of the native-mode stack pointer 

When you switch 10 emulation mode, the upper 8 bits of your stack pointer wiJl be lost 
Thus, this value must be saved somewhere so that it can be restored to its original value 
on exit from this routine. The most common technique is to save the value of the 
entire native-mode stack pointer on the emulation-mode stack. 

♦ Note: The main and auxiliary stack-page switches cannot be used in native mode, 
Thus, when switching to emulation mode, you must use the main slack. 

The routine that follows saves the native-mode stack pointer and correctly sets the 
values for the direct-page register and the data bank register. IF your program requires 
other values for the direct-page and data bank registers, save these environment 
variables (as well as other register values in your environment) so that you can restore 
the values after returning from the firmware routine that you call, The EMULSTACK 
routine can be appended to the beginning of your own firmware calling sequence. A 
corresponding routine to restore the native-mode stack pointer is given in the section 
'Returning to Native Mode" later in this chapter. 

• fore entry, save YOUR environr. 
; Emulation stack pointer Is saved hare 
; 16-bit m and x 
/Temporary save of native-mode stack pointer 

;6-bi- - 

/Get stack pointer page 

/Is Stack already in page 1? 

;If so, don't get emulation stack pointer 

.'Set stack page to SOI 

/Get emulation stack pointer 
;Set emulation stack pointer 
;Save native-mode stack pointer 
; Emulation mode 

emulation mode 

;Set direct -page register to SC000 



/set data bank register ld SOQ 
,'Here continue with YOUR processing 



EMULSTACK 


EQU 


S0101QO 


TQEHUL 


REP 
TSC 
TAX 


#$30 




SEP 


#5-20 




XBA 






DEC 


A 




BEG 


ALREADYPG 




LDA 


*501 




K9A 






LDA 


-TACK 




TCS 




UaEAD':?:;! 


PHX 
SEC 
XCE 






PEA 


$0000 










■LDA 


H 




PHA 






PLB 
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Select emulation mode 

Setting the e bit to 1 puts the 65G816 into emulation mode and automatically sets the m 
and x processor status bits, to 1. The x bit forces the X and Y registers lo be treated as 
only 8 bits wide. The m bit Forces the accumulator to Ik treated as only 8 bits wide. 
This step also affects the size of the stack and the contents of the slack register, 
Specifically, the value of the upper 8 bits of the stack pointer is forced to a value of 
hexadecimal SOI (the same as the 6502). While you are in emulation mode, these 
upper 8 bits never change. Thus, the size of the stack is restricted to 256 bytes. 

Now you can set up the machine registers as required by the particular firmware routine 
and jSR. 



Returning to native mode 

To return to native mode, you must perform a set of steps complementary to the 
preceding steps that caused your program to enter emulation mode in the first place: 

Restore the native-mode stack pointer. 

n Restore your environment (if you are within the bank $00 entry routine). 

Then you can execute an RTL (return from subroutine long) to your point of origin 
(assuming that you performed a JSL to enter this code in the first place). These two 
return steps are explained in detail in the next two sections. 



Restore the native-mode stack pointer 

Return lo native mode. The following example is the complement to the preceding 
example that saved the native-mode stack pointer. Notice that this routine also returns 
the processor to native mode (it sets the e bit to and then sets the m and x bits to 0). 



pap 

XCE 

REE 

nx 

TXS 



*S30 



.■Preserve firmware's c learryl statue 
fSet native mode 
;It's still in fl-bit 

; Restore the carry flag 

16-bit 
,*Get native stack pointer from emulation stack 
;Set the native-mode stack pointer 
; Now restore the rest of your environment ! 



Restore your environment 

Restore all of your registers and flags to the values that your program expects to find on 
return. 

Assuming that you used a J5I. in the code that saved your environment and your native- 
mode stack pointer, you can now perform an RTL and resume execution of your 
program. 
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Other requirements for emulation-mode code 

The preceding example showed how to call firmware routines and specified thai the 
processor must lie in emulation mode, running in bank $00, to call the firmware 
routines. There may be other limes when you want to use emulation mode from banks 
«her than bank SOO, but you must observe other specific requirements. 

When you run e-mulaUon-mode code in a bank other than bank SOO, interrupts must be 
disabled. 

♦ Note: For AppleTalk applications, you must be sure that interrupts are enabled for 
al least 20 milliseconds out of every 1,1 seconds. For applications using the lick 
counter, interrupts must not be disabled for longer than 16.67 milliseconds or ticks 
will be lost 

When you are in a bank other than bank SOO with interrupts disabled, if you mix 6502 
and 65C816 instructions, the 65C816 instructions will still function as documented. Bui 
note that all 6502-cquivalent instructions behave the same as a 6502 regarding direct- 
page and stack-page wrapping The new 65C816 instructioas manipulate the stack and 
direct page, but do not wrap on a page boundary. Thus, you must exercise care when 
using these new stack- or direct-page instructions. 



Cautions about changing the environment 

If vou write your own subroutines Cor programs) that change some part of the operating 
environment, be sure that your code, at exit, puts things back the way it found them at 
entry. This is especially true of stack- and zero-page changes, data -bank- register 
changes, m, e, and x changes, speed-register changes, ROM-bank changes, and 
language-card changes. 

Slack and direct page 

For Apple II programs, the stack and die direct page (called the zero page for a 6502) 
must be in their proper 6502 locations and the stack must be 256 bytes long, For 
Apple I1GS programs, stack size and stack- and direct-page locations are at the 
discretion or the application. CCall the Memory Manager to obtain a new zero-page 
area). 

When you are in native mode, you can locate the stack anywhere within bank SOO. If the 
stack is located in memory at other than page 1 and the processor is switched to 
emulation mode, the upper half of die stack pointer will be lost (set io $01). When the 
processor is switched back to native mode, the upper half of the stack pointer will 
remain set to page $01. To avoid losing the nativemode slack pointer when switching 
to emulation mode, you must temporarily save the stack pointer so it can be restored. 
Sample code for saving and restoring Ihe native-mode stack value is shown in the 
examples. 
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Data bank registers and e, m, and x flags 

If your subroutine changes the contents of the data bank register or the e, m, and x 
flags, you should restore them to their original values. These registers affect not only 
the locations to which the index registers X and Y point and the length of the A, X, and 
Y registers; the contents of these registers also affect how the processor interprets its 
instructions, One can easily imagine an incorrect flag or register value causing a 
perfectly good program to fail. 

Speed- and Shadow- register changes 

Changing any of the bits in the Speed or Shadow register (see Chapter 3, "System 
Monitor Firmware") also affects how the system runs. (The Shadow-register bits of 
interest and the speed-change bit are all accessible through the pseudoregister called 
Quagmire. For assembly-language programming, you access these registers directly. 
See the Apple IIGS Hardware Reference for more information.) 

language-card changes 

If you change the active bank of the language card without restoring it on exit from your 
code, you again risk ruining another programmer's code. For example, the other 
programmer might have executed a JSR or JSL out of some code in a ROM bank or a 
particular bank of the language card. The return address of that routine is on the stack 
and points to the return address within that same bank of ROM or the language card. If 
your routine changes banks without restoring them to the original values upon exit, the 
system will fail. 



General information 

This section contaias other general information useful in creating 65C816 programs 
for the Apple 11GS. 



Apple Hgs Interrupts 

The Apple IIGS firmware provides improved interrupt support, very much like the 
enhanced Apple lie interrupt, support. Neither machine disables interrupts for 
extended periods. 

The main purpose of the interrupt handler in to support interrupts in any memory 
configuration. This is done by saving the machine's state at the time of the interrupt; 
placing the Apple IIGS in a standard memory configuration before calling your 
program's interrupt handler, and then restoring the original slate when your 
program's interrupt handler is finished. (Sec Chapter 8, " I ntcrru pi-Handler 
Firmware," for more information.) 



16 



Chapter 2: Notes for Programmers 



Boot/scan sequence 

The booi/scan sequence is initiated by selecting Startup: Scan from the Control Panel 
Slots menu. When the selection is made, the Apple IIGS starts at slot 7 and tests each 
slot for a boot device; the first device found is booted. The Apple 11GS starts its scan at 
the slot selected, ignoring all slots with a higher number, and works down to slot 1, If 
no boot devices are in the slots, the screen displays the message shown in Figure 2-1 
(the apple moves back and forth across the screen). 



Ctiocle Startup Device 



Figure 2- 1 

Boot-failure screen 

If slot 7 is enabled for an externa! device, the scan will proceed as just described. 
However, if slot 7 is set to AppleTaik and if the startup slot is set to slot 7, the firmware 
will try to boot AppleTaik, If RAM Disk or ROM Disk is selected, the SmartPort 
firmware will lie activated and the system will attempt to boot from the RAM disk or 
ROM disk (see Chapter 7, "SmartPort Firmware"). 



Program bank register 

The 65816 program bank register wraps within a 64K bank boundary. Data retrieval and 
storage, however, do not wrap within a 64K bank. This means that a program that 
executes at the top of a bank continues to execute at the bottom of the same bank, even 
between opcode and operaiui within a single instruction. Further, data retrieval and 
storage at the top of a bank simply roll over into the bottom of the next bank and 
continue as if no bank had been crossed. This same operation also occurs with 
indexed instructions. 



Important 

You must exercise core when writing code that deals directly with state- 
dependent hardware. The cycle-by-cycle operations of the 65C816 emulation 
mode and the 65C616 native mode differ. This behavior has to do with indexed 
Instructions. In one mode, a false read occurs at a given cycle, and In the other 
mode, a false write occurs. This difference can cause problems If soft switches and 
hardware expect one operation and get another. 
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Exchanging the B and A registers, XB A 

The A register (called the C register in native mode) is a 16-bit register used in both 
native and emulation modes. In native mode, all 16 bits arc used; in emulation mode 
8 bits are used for the A register and 8 bits are used for the B register (see Figure 2-2). 

C (A) Natrve mode 



pi i 1 1 1 1 1 inn 



Emulation mode 

Figure 2-2 

Accumulator for emulation and native modes 

Some programmers with 6502 experience might see the XBA instruction as a quick way 
to save the current contents of the A register while running in emulation mode. Then 
they might assume that it is appropriate to jump to system routines (that have to be 
executed from emulation mode anyway) and return, restoring the A register from B by 
another XBA. However, the contents of the B register (the old 8-bit accumulator 
value) will not be valid on return from any firmware routine. Thus, do not transfer 
control to any system code prior to restoring the A register with the following XBA. If 
you do, h is at your own risk. Although current documentation for the firmware entry 
points occasionally may show that the contents of the B register are preserved, this will 
not necessarily hold true for later releases of the firmware. 

For example, the following code works in 8-bit mode: 



X3A 


; Preserve A 


LDA FLAG 


;Do something with a 


LSR 


;Move LSB to carry 


XBA 


; Rest ore A 


The following 


code does not work: 


XBA 


/Preserve a 


LDA #A 




JSR rati? 


/Control is transferred 


XBA 


;RostOre A 



The A to me first line is not the same as the A in the fourth line. 
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This chapter describes the Apple IIGS system Monitor firmware, a low-level, 
command-driven program that lets you examine the machine state as well as create 
and test small machine-language programs. A professional developer will likely use a 
sophisticated assembler and debugger in addition to the system Monitor firmware. 

Note that when you use the Monitor to write machine- language programs, you can use 
the Monitor entry points listed in Appendix C, "Firmware Entry Points in Bank S00," 
to make your job easier. Also, if you use the disassembler, you will be interested in the 
table of disassembler opcodes in Appendix F, "Disassembler/Mini -Assembler 
Opcodes" 

The system Monitor firmware is a program dial you can use to create and test your own 
machine-language programs for the Apple HGS. From the Monitor, you can create 
programs that utilize various system-resident subroutines (a summary of which is 
contained in Appendix C, "Firmware Entry Points In Bank 500"). When you create 
your own programs or use the Monitor to examine programs that others have created, 
various features of the Monitor firmware assist you in your task. 

The Apple IIGS Monitor provides commands that 

c manipulate memory by examining it; by entering changes in either ASCII or 
hexadecimal form; by moving, comparing, or filling blocks of memory; and by 
searching for specified patterns 

3 view and change the execution environment (microprocessor registers and (lags) 

n execute programs from the Monitor 

□ Step through and trace program execution (hooks only; no code in current ROM) 

n perform miscellaneous tasks such as setting ihe display to inverse or normal video, 
displaying or setting the time and date, redirecting input and output, performing 
hexadecimal arithmetic, returning to BASIC via cold or warm start 

□ invoke the mini-assembler 
d invoke the disassembler 



Invoking the Monitor 

The system Monitor resides in read-only memory (ROM) beginning at location 
$FF69, or -151. To invoke the Monitor, you issue a Call statement to this location from 
the keyboard or from a BASIC program. When the Monitor is running, its prompt 
character (*) appears on the left side of the display screen, followed by a cursor. To 

use the Monitor, type 

Call -153 Return 

The prompt character and the cursor (a flashing blank space) appear: 
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Monitor command syntax 

You enter all Monitor instructions in the same format: Type a line on the keyboard 
and press Return. The Monitor accepts the line using ihe I/O subroutine GETLN. A 
Monitor instruction can be up to 255 characters, followed by a carriage return, 
CGETLN is described in Chapter 4, "Video Firmware.") 

A Monitor command can include four kinds of information: memory-bank number, 
addresses, data values, and command characters. You type addresses, memory-bank 
numbers, and data values in hexadecimal notation 

'Ihe microprocessor in Apple II computers prior to the Apple HGS could address 
memory only in an address range from to 65,535. The Apple IIGS, on the other 
hand, can address up to 256 banks of 65,536 memory locations each. Thus, there is a 
need for a memory-bank address qualifier for the Monitor commands. You will see 
the complete address represented as ( bank/ address) , where bank is to be specified 
as two hexadecimal digits and address as four hexadecimal digits. 

When the command you type calls for an address, the Monitor accepts any group of 
hexadecimal digits, automatically providing leading zeros to fill out the width of the 
field of digits. 



Monitor command types 

There are two distinct types of Monitor commands: commands that perform an 
operation (such as examining or filling memory) and commands thai change a 
register value- 

For commands that perform an operation, each command you type consists of one 
command character, usually the first letter of the command name. When the 
command is a letter, it can be either uppercase or lowercase. The Monitor recognizes 
46 different commands. Some of them are punctuation marks, some axe letters, and 
some are control characters, 

* rVofe Although the Monitor recognizes and interprets control characters typed on 
an input line, control characters do not appear on the screen. 

For commands thai affect the contents of a register, each command you type consists 
of a value and a register name. For register names, the Apple I1GS Monitor does 
require that the register name be entered using the proper case (uppercase or 
lowercase). The syntax of a register-modifying command is 

I value} = | register} 
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When you use a register-display command, the appropriate case for you to use to 
modify the register contents is shown in the display for each register. Be certain to 
note whether the register name is uppercase or lowercase and to use the correct case 
when selling a register value. 

Table 3-1 lists the Monitor commands and their syntax grouped by type. In Table 3-1 
and in the rest of this chapter, the command formats often specify addresses from 
which data is obtained or to which data is sent The source and target addresses take 
the form 

bank/ address 

where bank is an optional bank number Cone or two hexadecimal digits) and address 
is the address (one to four hexadecimal digits). The bank number, if present is 
separaled from the address by a forward slash (/) character. To make ihe command 
formats more understandable, several terms arc introduced here, each of which may 
be used in lieu of bank! address. Note that each of these terms uses exactly the same 
format: an optional bank number and the address. The purpose of these substitute 
forms is to make the command formats (especially within tables) easier to understand 
at a quick glance. 

The following terms may be used 



from_address 
io_address 

start address 



vat J 6 
vaJ64 

vatJO 

mm/ dd/yy 
hh'.mmtss 



An address (with optional bank) that serves as a data destination 

An address (with optional bank) at one end of a range of addresses 

An address (with optional bank) at the other end of a range of 

addresses 

An address (with optional bank) at which the Monitor will start an 

operation 

An 8-bit (1-byte) value specified as two hexadecimal digits 

A l6-bit (2-byte) value specified as four hexadecimal digits 

A value expressed as up to eight hexadecimal digits 

A value expressed as decimal digits 

Three 8-bit values separaled by forward slashes 

Three 8-bii values separated by colons 
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Table 3 I 

Monitor commands grouped by type 

Command fyp* 



Command formal 



VlBwfng and modifying memory 
Display single memory location 
Display multiple memory locations 
Terminate memory-range display 
Modify consecutive memory 

Move data in memory 

Verify memory contents 

Fill memory (zap) 

Pattern search (specified in four 

ways; any or all forms may be 

combined in a single search 

request) 

Vis wing and modifying registers 

Examine registers 

Modify accumulator 

Modify X register 

Modify Y register 

Modify D register 

Modify DBR register (bank) 

Modify program bank register 

Modify stack pointer 

Modify processor status 

Modify machine-state register 

Modify Quagmire register 

Modify 16/8-bit accumulator mode 

Modify 16/8- bit index mode 

lt__lr« 

Modify native/emulation mode 
Modify language-card bank 
Modify ASCII filter mask 



[from_address\ 

{from_address\ . {to_addms\ 

Control-X 

{ destination ] : [vat] ( val) { » literal ASCW \ 

{'JlipASaP) {val} 

{ destination) < lfrom_address) . [ to_address | M 

[destination) < {from_addre$$) . { to_address)V 

\vat)< ifmm_address) . [ to^address) Z 

\ { val) \<ifrom_address) . { to_addms)P 

\ 1 ' 123t • ) \<{from_address) . ( to_address)P 

\ [ "literal ASCU" [ \<ifrom_address) . ( to address) P 

\ { val] 6} \<{fram_address) , [ to_address)P 

Control-E 
[vail 6)= A 
{ vaU6) =X 

lWtl6]~Y 

lvall6)=D 
[ val) =B 
ival)=K 
{ val 16) =S 
{vaI)=P 
[val}mu 
/|=Q 
ival)=m 
I val) =x 

1 val) -e 
( val) =L 
[ vat) «=F 



(continued) 
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Table 3-1 (continued) 

Monitor commands grouped by type 



Command fypi 



Command formal 



M jcclaneous 






Begin inverse video 


I 




Begin norma! video 


N 




Change Lime and date 


^X^mmfddfyy hhxrnm 


iSS 


Display lime and date 


T 




Redirect input links 


( slot) Control-K 




Redirect output links 


[slot] Control -P 




Change screen display to text 


Control-T 




Change cursor 


Control-* ( new_cursor_ 


character} 


Convert decimal to hexadecimal 


-IvallO) 




Convert hexadecimal to decimal 


{val64\*> 




Perform hexadecimal math 






Add 


[val64\ + {val64\ 




Subtract 


\val64)-{vat64\ 




Multiply 


\val64}*\val64) 




Divide 


\val64}_{val64) 




Jump to cold-start BASIC 


G0fttfOl-B 




Jump lo warm-start BASIC 


Control-C 




Jump to user vector 


Control-Y 




Quit Monitor 


Q 




Program execution and debugging 






Go (begin) program in bank SOO 


{ sta rt _address}G 




Execute from any memory bank 


l$tar(_addre$$}X 




Restore registers and flags 


Control-R 




Resume execution 


istart_address)R 




Perform a program step 


{sta rt_address}S 




Perform a program trace 


[sta rt_address)T 




Disassemble (list) 


[start _address}L 
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Monitor memory commands 

The Monitor commands thai directly affcci memory arc discussed in this section 
These include commands to examine and change memory locations, search for 
specific combinations of memory contents, change memory contents individually or 
in blocks, and compare memory blocks. The Monitor presents memory dumps in 
both ASCII and hexadecimal formats. You can use either notation to enter youf 
requests for changes 10 memory. 

When you use the Monitor lo examine and change the contents of memory, the 
Monitor keeps track of the address or the last location whose value you inquired about 
(caUed the last-opened location) and ihe address of the location that is to have its 
value changed next (called the next changeable location) In addition, once you 
have specified a bank number in one of your iastructions, die Monitor continues to use 
that bank number with all other instructions until you explicitly change it 

In the paragraphs that follow, the memory-contents displays are based on what you 
would see if you were using the display in 80-column mode. When in 40-coIumn 
mode, the Apple ttGS Monitor dumps memory 8 bytes per line. When in 80-column 
mode, the Apple; IIGS Monitor dumps memory 16 bytes per line. 

Table 3-2 lists the Monitor memory commands. 

Table 3-2 

Commands for viewing and modifying memory 

Command lyps 



Command format 



Display single memory- location 
Display multiple memory locations 
Terminate memory-range display 
Modify consecutive memory 

Move data in memory 

Verify memory contents 

Fill memory (zap) 

Pattern search (specified in four 

ways; any or all forms may be 

combined in a single search 

request) 



{fmm_address} 

\from_address] . \ to_address) 

Control-X 

\ destination 1 : ( vat} i vol) ( - literal ASCII* \ 

i'JlipASCW) {vat) 

( destination \ < i/rom_address} . ( to__address] M 

{ destination) < [fmm_address) . { to_address\V 

[ val) < {from_address I . £ to_address ) 7, 

\ { val] \ < [fmm_address\ , f to_address} P 

\ 1 ' 123f \ \< l/rom_address] . [ ioaddress)? 

\ [" literal ASCII" ) \<lfrom_addre$s) . { tojOddresslP 

\ [vail 6] \< {from_address] . I to address}? 



Monitor memory commands 



25 



Examining memory 

The syntax required to display a single memory location is 

| bank/ address I Return 

If the Monitor is already examining the bank desired, you don't have to include the 
bank number in the instruction. Simply type the address and press Return. However, if 
you're not sure which bank the Monitor is in, include the bank number as shown in the 
example. The Monitor responds with the bank and address you typed 
{bank ! address), a colon, and the hexadecimal contents of the location. For 
example, to examine memory location hexadecimal 51000, next to the Monitor 
prompt (*) type 

'00/1C00 Return 

The bank and address are displayed as well as the contents of address S1000: 

00/lQO0;Z0- 

♦ Note. Dollar signs (5) preceding addresses that appear in running text signify that 
the addresses are in hexadecimal notation; however, dollar signs are ignored by 
the Monitor and must be omiued when typing instructions. If location $1000 had 
contained ASCII code, the ASCII equivalent would be displayed on the far right of 
the screen, as the Following example shows; 

*1000 Return 

(Notice that the bank address was not entered because you know that you are in bank 
$00.) The result is 

00 / 1 . 

$■ Abie. ASCII codes are decoded in the rightmost 8 spaces of your display. Printable 
ASCII character* are displayed as normal characters; nonprintable characters are 
displayed as periods (.)• If you are using the Monitor in 80-column mode, the 
ASCII characters will lake up the rightmost 16 spaces instead of 8, and 16 sets of 
hexadecimal digit pairs corresponding to the byte value* stored in the displayed 
memory range. 

When you change Lhe contents of memory, the Monitor saves the address of the last 
location in which you changed the contents and the address of the next location lo be 
changed — in other words, the last-opened location and the next-changeable 
location, 



r 
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Examining consecutive memory locations 

You may want to examine a block of memory locations, such as from S1000 to $1007. 
Simply type the starting address, a period, and the ending address and then press 

Return: 

•1000,3007 Return 

The contents of the memory locations are displayed as Follows: 

00/1000:51 -32 13 4 4 45 55 00 00 -ABCDEU,. 

If you type a period (.} followed by an address and then press Return, the Monitor 
displays a memory dump: the data values stored at all the memory locations from the 
one following the last-opened location to the location whose address you typed 
following the period. The Monitor saves the last location displayed as both the lasi 
opened location and the next-changeable location. In these examples, the amount of 
data displayed by the Monitor depends on the difference between the address of the 
last-opened location and the address after the period. 

00/1000; 1I-A 
*.1C03 Return 

:SI:41 42 43 4 4 4 5 55 00 00 -BCDEO . . 

308:51 52 53 54 -FORS 

w 

When the Monitor performs a memory dump, it starts at the location immediately 
following the last-opened location and displays that address and the data value stored 
there. It then displays the values of successive locations up to and including the 
location whose address you typed, but shows only up to 8 (or 16) values on a line. 
When il reaches a location whose address is a multiple of 8 (or 16), that is, one whose 
address ends with an 8 (or if 16, an address that ends with a 0), it displays that address 
as the beginning of a new line and then continues displaying more values. 

If you have selected a large memory range to display and you wish to halt the display 
and resume entering other Monitor commands, press Control X. This terminates the 
memory- range display. 

After the Monitor has displayed the value at the location whose address you specified 
in the command, it stops the memory dump and seis that location as both the last- 
opened location and the next-changeable location. If the address specified in the 
input line is less than the address of the last-opened location, the Monitor displays 
only the address and the value of the location following the last-opened location. 
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Changing memory contents 

The previous section showed you how to display the values stored in the Apple 1IGS 
memory system; this section shows you how lo change those values. You can change 
any location in RAM and you can also change the soft switches and output devices by 
changing the contenis of the memory locations assigned to them. 



Warning 

Use these commands carefully. If you change the contents of memory In any 
area used by the Apple Ites firmware or Applesoft, you may lose programs or data 
stored In memory. You can find a map showing the memory use by various parts 
of the system software in the Apple /tes Hardware Reference. 



Changing one byte 

Previous commands kepi track of the next-changeable memory location-, other 
memory commands make use of that location. In the next example, you open location 
S 1000 and type a colon ( : ) followed by a value: 

♦1000 Return 
00/1000:50 -P 
* ;M Return 

This entry changes the contents of the opened location to the value you requested. To 
verify the changes, again type 

Return 

The Monitor now disp 

"00:51 -T 

ft 

You can combine opening a location and changing its contents into a single operation 
by specifying the address, a colon, and the contents on a single command Inn 

0:41 Return 

As before, you can verify that the system obeyed your command by typing 

*iooo Return 

The Monitor now displays 

00/1000:41 - A 
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You can change a byte to an ASCn code using ihe character instead of the numeric 
value. Use the same syntax as before, but enclose the ASCII characters in double 
quotation marks, as follows: 

•100D:"a" 

To verify that the location has been changed, type 

•loco Return 

Again, the bank! address and location contents are displayed. 

00/lOOO:£l-a 

• 

Note that when you change the contents of a programmable memory location, the new 
value that you provide entirely replaces the value that was in that location to begin 
with, "This new value will remain there until you replace it with another value or until 
you turn off the computer. Further information about this operation is provided in the 
section "ASCII Filters for Stored Data" later in this chapter. (If you are using the ASCII 
input mode, the filter will affect the data that you have entered.) 

Changing consecutive memory locations 

You don't have to type a separate command with an address, a colon, a value, and a 
Return for each location you want to change. You can change the values of man', 
memory locations at the same time by typing only the initial address and a colon, 
then all the values separated by spaces, and then Return. 'Ihe only limitation is that the 
total length of the string, including the address, colon, ail of the values and spaces, 
and the Return, must not exceed 255 characters. Using this method, you could change 
100 or more locations in a single entry line. Note that you don't need to type leading 
zeros, a feature that provides even more possible data entry locations in a single 
command line. 

f The Monitor stores the consecutive values in consecutive locations, starling at the 
* location whose address you typed. After it has processed the string of values, il takes 
the location following the last-changed location as the next-changeable location. 
Thus, you can continue changing consecutive locations without typing an address on 
The next input line by simply typing another colon, a space, and more values. In the 
following examples, you first change some locations and then examine die in to verify 
the changes. 

*1C0C:5€ 57 58 59 €0 61 62 63 64 65 Return 

The contents of locations S10OO through $1009 have been changed, as you can see by 
examining those locations: 

I 1000.1009 Return 
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As before, the memory-bank number and ihe starting memory address precede liie 
values you typed, and the ASCII values are displayed at the right, 

I DDiSfi 57 5B 53 60 £1 $2 63 &A 65-WXY 'abcde 

In the next example, you use the colon to continue a data entry, as noted in the 
preceding description; 

*1Q0C:41 Mk 43 Return 
*j3130 32 33 Return 

.1006 Return 
0071000:41 42 43 30 31 32 33-A8C0123 

Note that you can enter data in either single-byte Cone or two hex digits) or double- 
byte (three or four hex digits) or triple-byte (five or six hex digits) or quadruple-byte 
(seven or eight hex digits) units, When a double-byte quantity is entered, liic Monitor 
stores the bytes in low-byte, high-byte sequence (the reverse of the way you entered 
them), as demonstrated in the example Q130 entry) above. This is useful when you are 
specifying address entries for the mini -assembler. You will find more of this kind of 
entry demonstrated in the section "The Mini-Assembler" later in this chapter. 

ASCII input mode 

You can enter ASCII data in two different ways. One way is called literal ASCII; the 
other way is called yfljp ASCII. 

<* Note: The ASCII filter will affect the final form of your data when ASCII input mode- 
is used. See the section "ASCII Filters for Stored Data" later in this chapter for more 
information. 

To enter data in literal ASCII format, type the character siring you wish to enter 
between a pair of double quotation marks. The characters you enter are stored in 
ascending order in the same sequence in which you typed them. In some cases, you 
might want to store the characters in reverse order, with the last character stored at ihe 
lowest memory address. You use flip ASCIJ for this entry mode, Flip ASCII is entered 
by using single quotation marks in place of double quotation marks. Note, however, 
that flip ASCII is limited to four characters maximum. The following example 
demonstrates literal ASCII data entry: 

1000 j "ECHO" Return 

1000.1003 Return 

00/lCOOi C5 C3 C8 CF - ECHO 

The next example demonstrates flip ASCII data entry: 

lOOOl'KHD 1 Return 

1000.1003 Return 

00/1000: CF CB C3 C5 - OHCE 
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ASCII filters for stored data 



I. 

When you perform any manipulation of ASCII code, you must consider the literal 
ASCII format of the stored data. For example, do you want the data to be stored in 
[ ASCII format with the most significant bit set (to be compatible with the I/O firmware 
for display purposes) or directly in true ASCII l jrmai, where what you type exactly 
follows the ASCII standard? The format can be changed using any filters provided by 
I ibe Monitor. The filter can be any hex value from $00 Cmaximum filtering) to SFF (no 
[filtering, that is, all source bits pass through the filter unmodified). 



Format of stored data 

El E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC 
61 62 6364 65 66 67 68 69 6A 6B 6C 
21 22 23 24 25 26 27 28 29 2A 2B 2C 



; Ttie filter formats are as follows: 

Entry Fiii»r 

"abcdefghijkl" FF (default Tiller) 
7F 
3F 

The syntax for changing filters i$ 

I filler- value) =F Return 

For example,, if you type 

|7F-r Return 

the system uses the 7F filler formal 

This means that when you search for any pattern in memory, you must know which 
format is used. If FF is used, abc appears in hex as El E2 E3; if 7F is used, abc appears 
[is 6l 62 63. Thus, if you perform a pattern search for El E2 F.3 and the formal used was 
7F, you will not find the correct pattern 

The input ASCII character is Ai\T>ed with the filter value and then stored in the search 
buffer. 



Moving data in memory 

You can copy a block of data stored in a range of memory locations from one area in 
memory 10 another by using the Monitor's Move (M) command. To move a range of 
memory, you must tell the Monitor both where the data values are now situated in 
memory (the source locations) and where the data values are to go (the destinatii m 
locations). Vou give this information to the Monitor by providing three addresses: the 
id&ess i'! ihi Bra location In the destination and the addresses of the srartiag and 
ending locations within the source range. You specify the siarting and ending 
addresses of the source range by separating them with a period. You separate the 
destination address from the range addresses with a less-than character (<), which you 
may think of as an arrow pointing in the direction of the move. Finally, you tell the 
[Monitor that this is a Move command by typing the letter M (in either lowercase or 
uppercase). 
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The formal of the complete Move command looks like this: 

I destirmiion } < [from address} .[to addrets | M 

To move data from $1000 through $1009 to locations beginning at $2000, type (he 
nation, the starting address, and the ending address followed by the letter M. 
Note dial as you type the address values, the words in braces and the braces themselves 
are replaced by the hexadecimal addresses that you wish lo use, The example uses 
bank $00 as both the source and the destination. You can, however, specify the 
complete bank address within either of die source addresses or in die destination 
address, because everywhere thai the Monitor requires an address, it will also find the 
combination of [bank/ address acceptable as well. 

•200CK1G00.1009K Return 

Now examine the data you moved by using the examine procedure- Type ihe starting 
address and the ending address and press Return: 

■2 000. 2 00 9 Ketum 

The data returned to the display looks the same as it did when you examined Incan wis 
SI 000 through $1009: 

00/2000 :CF C8 C3 C5 60 61 62 63 64 65-OHCE" abede 

The Monitor moves a copy of the data stored in the source range of locations to the 
destination locations. The values in ihe source range are left unchanged. The Monitor 
remembers ihe last location in the source range as the last-opened location and the 
first location in the source range as the next-changeable location If the second 
address in the source range is less than the first, then only one value (thai of the first 
location in the range) will be moved. 

If ihe destination address of the Move instruction is inside the source range of 
addresses, ihen strange (and sometimes wonderful) things happen: The locations 
between the I x ginning of die Mumr range and the destination address are treated as a 
subrange, and the values in this subrange are replicated throughout the source range. 
The section 'Special Tricks With the Monitor" later in this chapter provides an 
interesting application of this feature. 
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Comparing data in memory 

You can use the Verify CV) command to compare two ranges of memory using the 
same formal you use b ■ move a range of memory from one place to another. In fact, a 
Verify command can be used immediately after a Move command to make sure that 
the move was successful 

The Verify command, like the Move command, needs a range and a destination. The 
ix of the Verify command is identical to the Move command, except thai you type 
a v in place of an M: 

{destinaiionaddressi < [starting address) . ■ ending address \v 

The Monitor compares the values in the source locations with the values in the 
locations, beginning with the destination address. If any values don't match, the 
.Monitor displays the first address at which a discrepancy is found and the two values 
that differ. If you enter the example shown for the Move instruction and then change 
one byte at the destination, you can use the Verify command to find the di 
Change the first location to hex 41 (it was hex 56) and then use the Verify command: 

*2Q00;4i Return 
*2O0Q<1OOO. 1009V Return 

If there are no discrepancies, you will not get a display. In this example, because you 
will have caused a discrepancy, the fallowing is displayed; 

00/1000:56 [41) $2000 

sid:c 

location 51000 contains 56; location $2000, however, contains 41, 

The Verify command leaves the values in both ranges unchanged. The last-opened 
location is the last location in the source range, and the next-changeable location is 
the first location in the source range, just as in the Move command If the ending 
address of the range is less than the starting address, the values of only the first 
locations in the source and destination will be compared. Like the Move command, 
ihe Verify command also does strange things if the destination address is within the 
source range. Again, see the section "Special Tricks With the Monitor" later in this 
chapter. 
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Filling a memory range 

You can fill a memory range with a specific value by using the Monitor Zap (Z) 
command. You tell the Monitor where and how to zap memory by providing three 
pieces of information: the value to fill, the starting address, and the ending address. 
You separate the value from the starting address by using a less-chan character (<), 
You separate the beginning and ending addresses of the range with a period. The 
syntax for Zap is 

•; value) c { startingaddress} , ( i ending_address) ?, Recurn 

When Zap operates, the value you have selected is filled into the entire range, 
including the starting and ending addresses. 



Searching for bytes in memory 

The Pattern Search (P) command allows you to search for one or more bytes 
(hexadecimal values, ASCII characters, or a combinau'on of the two) in a range of 
memory. The synlax of the pattern search instruction is as follows: 

• \ { valued) or " literal ASCII" at 'flip ASCII ' \\<{ starting_address.ending_address)? 

The byte values are entered end to end with no intervening spaces. This format is 
required by the Pattern Search command because you are looking for a string of 
values. Note that you must enter leading zeros. For example, a search for the siring of 
characters OD followed by OA between locations 1200 and 1400 would be entered as 

•\0D OA\«12Q0.HOQP Rerum 

If you arc looking for a siring of characters, you can enter the characters delimited by 
double quotation marks as shown here: 

•V'Mr. Gnndbar"\,<i200.1400P Return 

ir the pattern is found, the beginning location is displayed. For example, if the pattern 
is located with its first byte at location S1300, the following is displayed: 

: 4 1 -A 
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Registers and flags 

The Apple IlGS system uses a number of registers and control flags (bits) to perform its 
various functions. Table 3-3 lists these registers and flags. 

fable 3-3 

Registers and flags 



Peglster 



Flag 



Accumulator 
Index register 

Index register 
Stack pointer 
Direct zero page 
Processor status 
Data bank 
Program bank 



M 

m 
x 

c 
L 



Machine state 

Quagmire M£ 

Accumulator mode: 
Index mode 
Emulation mode 
Language-card bank 



The A, X, and Y registers are the workhorses of the assembly-language program mi-i. 
The P register contains all of the system status flags. The D register is the 65816 direct- 
page register that controls the placement of the zero page of the processor. The S 
register is the stack pointer. The K register contains the upper 8 bits of the program 
I counter because the 65816 operates anywhere in a 24-bit address space. 

I la books that describe programming for die 65816, the upper 8 bits of the accumulator 
are sometimes called the D register. These programming books also refer to die 1 6-bit 

I accumulator as the C register, the program bank register as PBR (the upper 8 bits of the 
program counter), and the data bank register as DBR (the upper 8 biLs applied to the X 
and Y registers). For convenience, the Monitor renames these registers as follows: 

1 The Monitor 11 register display shows the DBR contents. 

n The Monitor K register display shows die PBR contents. 

n The Monitor A register display shows the 1 6-bit accumulator contents, whether 8 or 
16 bits. 

d The Monitor does not separately display the upper 8 bits of the accumulator. 

Note thai the Monitor does not display the current contents of the program counter 
register. If you want to step or trace a program, you must create your own separate 
routine to display the program counter contents along with these other registers. 
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The M register represents the machine state. The individual bits of this register are 
described in the summary at the end of this chapter. You can find an in-depth 
description of the meaning of these bits in the Apple IIGS Hardware Reference. 

The Q register, also called the Quagmire register, is not actually a hardware 
machine register, but a pseudoregister made up of conirol bits located elsewhere in 
the system, One bit (bit 7), selects high-speed operation. CEarlier Apple n series 
computers operated only at 1 MHz; the Apple IIGS can operate either at 1.0 MHz or 2.8 
MHz.) Bits 6 to enable and disable various shadowing options. Shadowing, when 
enabled, writes the same data to banks $00 (or 501) and $E0 (or SE1) in selected an 
as defined by the individual shadowing bits. 



The environment 

The complete set of registers and flags is called the environment. When your program 
encounters a break or another kind of interrupt condition, this environment is saved 
by the Monitor, When you issue a command to resume execution, the environment is 
restored as it was when the interrupt occurred Your program resumes as though 
nothing had happened. If you change the contents of the registers and flags dial are 
displayed, then the changes become the new environment that your program 
encounters when it again begins to execute. You also change the registers and flags to 
set up a new environment for a program that you might write and execute using the Go 
command, discussed later in this chapter. 



Examining and changing registers and flags 

The microprocessor's register contents change continuously during execution of a 
program, such as the Mi lOfti r firmware. Using the Monitor, you can see what the 
register contents were when you invoked the Monitor or when a program you were 
debugging stopped at a Break CBRK) or a COP instruction or as a result of an 
unscrvtced hardware abort condition. 
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Table 3-4 lists the commands that relate to system registers. 

Table 3-4 

Commands for viewing and modifying registers 



Command typ* 



Command lormaf 



Examine registers Controi-E 

Modify accumulator { vall6) =A 

Modify X register { vat 16) =X 

Modify Y register { vall6) -Y 

Modify D register { val J 6} -D 

Modify DBR register (bank) { vat) -B 

Modify program bank register { val) =K 

Modify stack pointer { vaU6}=S 

Modify processor status { val) =P 

Modify machine-state register {val) =M 

Modify Quagmire register [ vol) =Q 
Modify 1 6/8- bit accumulator mode {val)=m 

Modify 16/8-bk index mode {val\=x 

Modify native/emulation mode {wi/)=e 

Modify language-card bank { vol) =L 

Modify ASCII filter mask { val\ -F 



When you call the Monitor, it stores the contents of the microprocessor's registers and 
flags in memory. The registers and flags are stored in the order A, X, Y, S, D, P, B, K, 
M, Q, L, m, x, and e. When you give the Monitor a G instruction, the Monitor loads 
the registers in this same sequence before it executes the first instruction in your 
program. The m, x, and e flags are part of the processor status register (P). However, 
because the registers and flags are reloaded in the sequence shown, whatever value you 
have placed in m, x, and e will override any such value you might have placed in P. 

♦ Nate: If you set ihe value of the c flag to 1, the 65816 automatically sets the value of m 
and x to 1. This puts the processor into 6502 emulation mode, forcing it to have an 
8-bit accumulator and index registers. Additionally, the upper 8 bits of the stack 
pointer are forced to a value of 01. 

Press Conlrol-E and then Return to invoke the Monitor's Kxamine instruction. This 
action displays the stored register values and flags and sets the location containing the 
ems of the A register as the next-changeable location, The example follows: 

•Coiitrol-E Return 

The registers and flags are displayed as follows: 

You can change the values in any of these locations by typing the new value, an equal 
sign (=), and the letter for the register or flag to affect and pressing Return. In the 
following example, the first two locations are changed, and the registers and flag bits 
ire again displayed to verily the change. 
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Change A to the value 1234; 

•1234-A Return 

Change X to the value 006 A: 

-0Q6A-X Return 

Execute the Examine instruction: 

* Control-!* 

'Ihe registers and flags are displayed to verify the changes; 

234 X=006A Y-C3CB 5=01F4 D-0Q00 P=00 B=00 K-00 M-OC Q=B0 L-l n-1 x-1 «-l 

•$ Note. If you are using the Monitor to debug a program running in 6502 emulation 
mode, ihe values for the microprocessor registers will revert to their 6502 
equivalents, For example, the A, X, Y, and S registers will be able to hold only 8 
bite each. Even if you specify (and display) a value thai exceeds 8 bits, only the low 8 
bits of the value you enter will be used when the system resumes 6502 emulation. 



Summary of register- and flag-modification commands 

The following commands can be used to modify the registers and (lags. Note that all of 
these are case sensitive. To change the register you want to change, you must use the 
case (uppercase or lowercase) shown in the registers and flags display. The case of ihe 
letters is the only way ihe Monitor can distinguish between flags and registers in this 
situation (for example, compare X and x and M and m in the following list). 



Change fo 


Syntax 


Accumulator 


( vat 16] -A 


X register 


lvaU6)=X 


Y register 


I val!6) -Y 


D register 


ivall6}=D 


DBR register (bank) 


1 vat) -B 


Program bank register 


{ val\ -K 


Stack pointer 


i vall6\ -S 


Quagmire register 


iml)=Q 


Machine register 


ival)=U 


m flag 


t val\ «m (val = for 1 6-bit accumulator, 




vol = 1 for 8-bit accumulator) 


x flag 


( vat) =x (val = for l6*bit index registers 




val = 1 for 8^bil index registers) 


e flag 


{ val) =e {val = for native mode, 




val= 1 for 6502 emulation mode) 


Filler value for ASCII modes 


{ ml) =ff (mt = any value from $00-5 FE, 




default val - FF) 


Language -card bank 


\ ml) -L (val -0 or 1) 
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Miscellaneous Monitor commands 

Other Monitor commands enable you lo change the video display format I 

normal to inverse and back and lo assign input and output to accessories in expansion 

slots. Table 3-5 lists these miscellaneous commands, 

Totol© 3-5 

Miscellaneous Monitor commands 






Command ryp« 


Command format 


Begin inverse video 


I 


Begin normal video 


N 


Change lime and date 


=T=mmJdd/yy hh: mm-.ss 


Display time and date 


=T 


Redirect input links 


1 Slot] Control-K 


Redirect output links 


( slot) Cootrol-F 


Change screen display to text 


Control-T 


Change cursor 


Control- A I new cursor character] 


Convert decimal to hexadecimal 


= {vallO\ 


Convert hexadecimal to decimal 


\va!64] = 


Perform hexadecimal math 




Add 


{val64\ + \val64] 


Subtract 


\vat64\- {val64} 


Multiply 


{val64\*{val64\ 


Divide 


[val64\ \val64) 


Jump to cold-start BASIC 


Comrol-B 


Jump to warm-start BASIC 


Control-C 


Jump to user vector 


Control-? 


Quit Monitor 


Q 



Inverse and normal display 

You can control the setting of the inverse/normal mask location used by the COUT 
subroutine from the Monitor so that all of the Monitor's output will be in inverse 
format. The COUT routine is described in Chapter 4, "Video Firmware " The Inverse 
command (I) sets the mask so that ail subsequent input and output arc displayed in 
inverse formal. 

■I Return 

To swilch the Monitor's output back to normal format, use the Normal command (NY 

*N Return 
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Working with time and date 

You can display or set the time and date directly from the Monitor. CNormally, time 
setting is handled through the Control Panel, which is described in Appendix G. "The 
Control Panel,") 

Here is the format for displaying the lime and date: 
-r Return 

If you warn to set the time and date, use the following format (for decimal number 
entry): 

= r> nnfdd/yy hh • mm: ss 

where nn is the month (range 1-12), dd is the day (range 1-31), yy is the year (range 
0-99), hh is the hour (range 0-23), mm is the minutes (range 0-50), and ss is the 
seconds (range 0-59). The delimiters slash (/) and colon (:) are shown as the 
suggested format because these delimiters conform to what a user normally expects to 
see. However, any delimiter other than an apostrophe ( T ) can be used to sepa'cu.- \U,. 
values entered. 



Redirecting input and output 

The Printer command, activated by Conirol-P, diverts all output normally destined 
for the screen to an interface card in a specified expansion slot, from 1 to 7. There 
must be an interface card in the specified slot or you wiJI lose control of the computer 
and your program and variables may be lost. The format of die command is 

I slot-number; Control-P 

A Printer command to slot will switch the stream of output characters back to the 
Apple IIGS video display. 

Don't issue the Printer command using a slot value of to deactivate the 80-column 
firmware, even though you used this command to activate it in slot 3. The command 
works, but it just disconnects the firmware, leaving some of the soft switches set for 80- 
column display. 

in much the same way that the Primer command switches the oulput stream, the 
Keyboard command substitutes the interface card in a specified expansion slot for the 
normal Apple DCS input device, the keyboard. The format for the Keyboard 
command is 

[slot-number] Conirol-K 

Specifying slot number For tlic Keyboard command directs the Monitor to accept 
mpm from the Apple IIGS keyboard 

The Printer and Keyboard commands are the equivalents of BASIC commands PR# 

and I 
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You can change the Monitor cursor from a flashing blank space K> whichever character 
you wish. Here is the formal for changing the cursor: 

I H 



Changing the cursor character 



Control-"' t new cursor character \ 

Here is an example thai sets an underscore (_} as your new cursor character: 

•control-* Return 



The underscore now appears as the cursor character. To restore the original cursor, 
specify that ihe new cursor is a delete character. 



Converting hexadecimal and decimal numbers 

You can convert up to 8-digii hexadecimal numbers to decimal values. The syntax is 

\vcdws\-\ Return] 

For example, type 

•CCCF- Return 

Hexadecimal S00OF is convened lo decimal 15: 

You can also convert a decimal number to a hexadecimal number. The syntax is as 

follows: 



*lw/wl Return 
For example 



type 



'-0015 Return 



Decimal 0015 is converted lo hexadecimal SO0000OOF: 

SOCCOODOF 
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Hexadecimal math 

You can use the Monitor to perform hexadecimal math. The Apple IIG5 Monitor can 
handle 32-bit addition, subtraction, multiplication, and division operations. The 
syntax for these operations is shown below. Note that multiplication shows a 64-bit 
result, and division displays both the remainder and the quotients Notice also that 
bank-address information provided in the entry of the data is ignored during the 
calculations. If you wish lo actually perform address calculations, you can convert 
your bank and address into a 6-digit hexadecimal quantity and use thai for i lu ■ 
calculations (just leave out the forward slash). 



Operation 

Addition 

Subtraction 

Multiplication 

Division 



Syntax 

Ival64\-{val64) 
\vat64)* \val64) 
{val64\ [ml64] 



Return 
Return 
Return 
Return CAn underscore character rather than 



the traditional forward slash is used to specify division.) 
Here are a few examples: 

*1234-a234 Rewm 
-> SQ0002468 

34 Return 
-> S00001268 
: Return 
-> 5 50000035 

-222 2 Return 
-» SFFFFEEF0 
'12-345STS9 Return 
-> SOO000O003ftE14 7A2 
*1234567fl_120 Return 
R-> SQOOOOODfl Q-> $00:02E65 
*0/23+l/23 Return 
-> $0000004 6 CBank-sddress information was ignored,) 
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A Tool Locator call 

From i he Monitor, it is possible to call the toolbox routines. However, the toolbox 
routines will most often be used by programs rather than by keyboard access through 
the Monitor, The syntax for the Toot Locator call is listed in detail in the summary at 
the end of this chapter. If you wish to use tool calls from the Monitor, see the 
Apple lies Toolbox Reference fur details about the tool numbers and parameter 
requirements for the tool of your choice. 

As an example of a possible use, here are two sample tool calls. The first call, once 
entered, allows you to type a line of text, followed by a carriage return. This first call 
returns a count, in hexadecimal, of the number of characters you typed. You will then 
Store the number you receive into a memory location and call another tool that will 
retrieve and type the characters to the display. 

This first tool call reads the keyboard, staring successive characters in locations 
beginning in memory location SO 12080 until you type a carriage return character. 

\c 2 o 1 20 fll OFF 8D 1 24 C\U Return 

After you input some text and press Return, the Monitor responds with a hex count of 

the number of characters you typed. If you typed 

THESE ARE MY LETTERS, Return 
the Monitor responds 

■15 



Now type the following line after the Monitor prompt to store that number you 
received into memory to set up for the tool to type Lhe lext The hex value that you 
enter in this memory-modification command is the same value that the tool returned 
as your character count. 

| 01/2080:15 Return 

The following command asks a tool to type the text 

M 1 20 80 lc C\V Return 



Back to BASIC 

Use the BASIC command, Control -B, to leave the Monitor and enter the BASIC that 
was active when you entered the Monitor. Normally, this is Applesoft BASIC, unless 
you deliberately switched to Integer BASIC. Note that if you use this command, any 
program or variables that you had previously entered in BASIC will be lost. If you want 

to reenter BASIC with youf previous prelum and variables intact, use the Continue 

BASIC command. Control-C. 

If you are using DOS 33 or ProDOS* press Control-Reset or use the Monitor Q (Quit) 
command to return to the language you were using with your program and variables 
intact. 
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Special tricks with the Monitor 

This section describes some more complex ways of using the Monitor commands, 
including 

□ placing multiple commands on a single command line 

D filling memory with a mutii pie-byte pattern 

n repeating commands 

n creating your own commands 




Multiple commands 

You can put as many Monitor commands on a single line as you like, so long as you 
separate them with spaces and the total number of characters in the tine is less than 
254. Adjacent single-letter commands such as L, S, I, and N need not be separated by 

spaces. 

You can freely mix all of the commands except the Store 0) command. Because the 
Monitor lakes all values following a colon and places them in consecutive memory 
locations, the last value in a Store command must be followed by a letter command 
before another address is entered. You can use the Normal command as the letter 
command in such cases; it usually has no effect on a program and can be used 
anywhere. 

In the following example, you display a range of memory, change it, and display it 
again, all wiih one line of commands: 



•1300.1307 130DT38 39 1 S 1300.1302 Return 
00/1300 - 00 00 00 00 00 00 00 00 38 39 01- 



. . S 3 



If the Monitor encounters a character in the input line that j| does not recognize as 
either a hexadecimal digit or a valid command character, it executes all the 
commands on the input line up to that character. H then grinds to a halt with a beep 
and ignores the remainder of the input line. 
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Filling memory 

The Move command can be used Jo replicate a pattern of values throughout a range of 
memory. To do this, first store the pattern in the first locations in the range: 

•130CU11 22 33-. "3 

• 

Remember the number of values in the pattern; in this case, it is 3- Use this number to 
compute addresses for the Move command, like this; 

(.start-number) c \ sfani . < end-number) M 

This Move command first replicates the pattern at the locations immediately following 
the original pattern, then replicates that pattern following the first replication, and so 
on until it fills the entire range: 

130<1 300.1 33 4M 

•1300,1317 Return 

00/1300 - 11 22 33 11 22 33 11 22 33 11 22 3.1 11 22 33 11-, "3. "3 . "3. "3 . "3. 

00/1310 - 22 33 11 22 33 11 22 33-"3 ."3 . "3 

» 

You can perform a similar trick with the Verify command to check whether a pattern 
repeats itself through memory. Verify is especially useful for verifying that a given 
range of memory locations all contain the same value. In the following example, you 
first fill the memory range from S1300 to $1320 with zeros and verify it; you then 
change one location and verify it again: 

*L30Q:C 

'130K13C0.1320H 
<13CC. 1320V 
•1304:02 

*1301<;13QQ.132QV 
L303 - 00 (02) 

1304 - 02 (00) 



The Verify command detects the discrepancy. 
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Repeating commands 

You can create a command line thai continuously repeats one or more commands. 
You do this by beginning the part of the command line lhat you want to repeal with a 
letter command, such as N, and ending it with the sequence 34 :n, where n is a 
hexadecimal number that specifies the position in the line of the command where you 
want to start repeating. For the first character in the line, n - 0. The value for n must be 
followed by a space for the loop to work properly. 

This trick takes advantage of the fact that the Monitor uses an index register 10 step 
through the input buffer, starting at location $0200, Each lime the Monitor executes a 
command, il slores the value of the index at location $34; when that command is 
finished, the Monitor reloads the index register with the value at location $34 By 
making die last command change the value at location 534, you change this index so 
lhat the Monitor picks up the next command character from an earlier point in the 
buffer. 

The only way to stop a loop such as this is to press Control-Reset; that is how the 
following example ends: 



*N 1300 


1302 34:0 Return 


1300 


- 


ll 


1302 


- 


30 


1300 


- 


1 1 


1302 


- 


33 


1300 


- 


i ! 


1302 


- 


33 




- 


:: 




- 


33 


13 CO 


- 






- 


32 


1300 


- 


i: 




- 


33 






CControl-Ri 


1 







CCoriU-oUReset is pressed here; the Monitor jumps to Applesoft) 
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Creating your own commands 

The User command, Control-Y, forces the Monitor to jump to memory location 
S03F8. You can put a JMP instruction there that jumps to your own machine-language 
program. Your program can then examine the Monitor's registers and pointers or the 
input buffer itself to obtain its data, For example, the following program displays 
everything on the input line after Control-Y. The program starts at location $0300; the 
command line that starts with $03 F8 stores a jump to $0300 at location S03F8. Here is 
the program, followed by a listing of the method by which it is entered into the 
Monitor. 



The program: 


1DX 




H0RE IDA 


2ZZ, x 


JSH 


COUT 


I NX 




CMP 


HAD 


BNE 


MORE 


JMP 


MONZ 



;<»et the index from location 5 33 

;Points to next character position in input, line 

;Get that character into accumulator 

;Output the character 

;Poinc to the next character 

;5ee if it is a carriage return 

;If not, go get more 

;Jump to standard monitor entry point (Call 

Entering the program into the Monitor: 

*300:A4 34 B9 200 20 FDED CS C9 flD DO F5 4C FF69 
*:?S:4C 300 
•Control-* THIS IS A 
THIS IS A TEST 

■ 

Notice that the target addresses for the JSR (jump to subroutine) instructions (value of 
hex 20) are entered directly as their 4-digit hexadecimal values rather than as separate 
byte pairs in reverse order as would normally have been required for the system 
Monitor in machines prior to the: Apple IIGS, You can enter full 32-bit addresses in 
this manner if you wish (up to 8 hexadecimal digits, forming a 32-bit quantity). 
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Machine-language programs 

The main reason to program in machine language is to get more speed. A program in 
machine language can run much fasier than the same program written in high-level 
languages such as BASIC or Pascal, but the machine-language version usually takes a 
lot longer to write. There are other reasons to use machine language: You might want 
your program to do something that isn't included in your high-level language, or you 
might just enjoy the challenge of using machine language to work directly on the bits 
and bytes. It is highly unlikely that a serious software developer will use the mini- 
assembler to produce large programs. However, the mini-assembler is a useful tool 
For quickly checking various basic concepts. Sometimes just the ability to examine 
memory is very handy. 

♦ Note: rf you have never used machine language before, you'll need to learn ihe 
language of the 65C816, To become proficient in machine-language programming, 
you'll have to spend some lime working with it and study at teasi one book on 
65C816 and perhaps also 6502 or 65C02 programming. 

You can get a hexadecimal dump of your program, move your program around in 
memory, examine and change register contents, and so on using the commands 
described in the previous sections- The Monitor commands in this section are 
intended specifically for you to use in creating, writing, and debugging machine- 
language programs. Table 3-6 lists the commands that relate to program creation and 
debugging. 

Table 3-6 

Commands for program execution and debugging 

Command typ* 



Command formal 



(iu (begin) program in bank $00 
Execute from any memory bank 
Restore registers and flags 
Resume execution 
Perform a program step 
Perform a program trace 
Disassemble (list) 
Enter mini-assembler 



[Start_address)G 
{ sia*i_address 1 X 
Control-R 

{stan_address)R 
{stan_address)S 
[start address jT 
{siart_address\L 

! 
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Running a program in bank zero 

The Monitor command you use lo start execution of your machine-language program 
is the Go command. When you type an address and the letter G, the Apple DOS 
restores all of the machine registers from their stored locations and begins executing 
machine- language instructions starting at the specified location. If you type only G, 
execution starts at the last-opened location. The syntax of the Go command is 

{ slart_addrea } G Return 

The iMonitor treats this program as a subroutine and executes a JSR to the program. If 
you want the routine to end by returning control to the Monitor, your program must 
end with an RT5 (return from subroutine) instruction to transfer control back to the 
Monitor. 

The Monitor has some special features that make it easier for you to write and debug 
machine-language programs-, but before you Learn about these, here is a small 
machine-language program that you can run using only the simple Monitor 
commands already described. The program in the example displays the letters A 
through Z. Store it starting at location $0500, examine it to be sure you typed it 
correctly, and then type 3 00G to start it running. 



"3Q0:A9 Cl 20 FDED 18 €9 1 

*30OG Return 

abedefghi jJslmnopqrst uvvxyz 



e9 DD DO F6 GO Return 



This is the assembly code that represents the preceding hand-assembled program: 



OCT 



LDA #C1 
JSR COOT 
CLC 

ADC fl 
CMP IOB 



/Place ASCII toe "A" into accumulator 
/Note; Mini-asserebler does not use labels 

Add 1 to contents of accumulator 

Compare contents to a value of ASCII ("Z"+1J 

It nsfej qg feacK and output §eguir value again 



The G instruction works only for code in bank $00. The system beeps if the user 
specifies any bank other than 500. The G instruction sets up a JSR to the code and 
expects this code to end in an RTS. 
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Running a program in other banks of memory 

You can run programs in banks other than bank $00 by using the X command instead 
of the G command. The X command restores ail of the machine registers from their 
siored locations and begins executing at the specified location. A JSL instruction 
(jump to Subroutine long) is performed instead of a JSR, and the user's code is 
expected to end with an RTL (return from subroutine long). The syntax of the X 
command is 

[start addre$$\Y. Return 



Resuming program execution 

You can resume execution of programs halted by a deliberate BRK (Break) instruction 
or Trace command by using the R command (Resume). Run programs in banks other 
lhan bank S00 by using the X command instead of the G command. The R command 
restores all of the machine registers from their siored locations and begins executing 
at the location you specify, A JMP instruction is performed instead of a JSR or JSL 
because the Resume command assumes that you do not intend to return to the 
Monitor. 






Stepping through or tracing program execution 

The Apple IIGS Monitor includes two commands for stepping through a program one 
instruction at a time and for tracing program execution (performing multiple steps). 
You put the Monitor into Step mode by using the S command. You put the Monitor 
into Trace mode by using the T command. (These commands, though present, are 
not fully implemented.) The Step command prints "STEP"' and returns control to 
the Monitor. The Trace command prims "TRACE" and returns control to the 
Monitor, If you want to implement your own Step and Trace functions, simply modify 
the Step and Trace vector locations to point to your own custom version of each 
routine. These vectors are shown in Appendix D, "Vectors." The formats for Slep and 
Trace are shown in the summary at the end of this chapter. 
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The mini-assembler 

The Apple IIgs mini-assembler included in the Monitor program allows you to enter 
machine-language programs directly from the keyboard, ASCII characters or hex 
values can be entered into a mini-assembler program exactly as you enter them in [he 
Monitor. The mini -assembler doesn't accept labels; you must use actual values and 
addresses. 

When you enter the mini-assembler, the Monitor prompt character changes from * 
to ! Cthe mini-assembler prompt) and assembles the first line of code (if a line or 
code is typed on the same line as the exclamation point that caused the mini- 
assembler to be entered). 



Starting the mini-assembler 

To start the mini-assembler, first invoke the Monitor from BASIC by typing 

Call -151 Return 

Then, from the Monitor, type 

! Return 

or 

! \bb/addrj ; {opcode,- I operand) Return 



Using the mini-assembler 

The mini-assembler saves one address, that of the program counter. Before you start 
typing a program, you must set the program counter to point to the location where you 
want the mini-assembler to store your program. Do this by typing the address 
followed by a colon. Then type the mnemonic for the first instruction in your 
program, followed by a space and the operand of the instruction, 

!300:T,DX *02 Return 

The mini-assembler converts the line you typed into hexadecimal format, stores it in 
iry beginning at the location of the program counter, and then disassembles it 
again and displays the disassembled line. The prompt is then displayed on the next 
line. 



00/0300- A2 02 



! :'X 
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The mini-assembler 



The mini-assembler is now ready io accept the second instruction in your program. 
To tell it that you want the next instruction to follow the first, don't type an address or a 
colon; type a space and the next instruction's mnemonic and operand and then press 
Return. 

Tin:- first Space after l be excbumUOll pOifU ■ ' '■ COOlfOlS the nature of the digits that 
Follow: 

□ A space means you want the next instruction to follow the first. 

□ A colon C i ) means hexadecimal information follows. 

□ A double quotation mark (") means ASCII information follow*. 

□ A number means an address follows. 
The first instruction is as follows: 

• lda $0,x Heium 

The mini-assembler assembles that line and is then ready for the next instruction. 

00/0302- B5 00 LDA C0,X 

| 

The following example shows the procedure for entering a program using the mini- 
assembler. The instructions you type are shown on a line with the prompt character 
C !); the assembled display is shown, in each case, on a line without a prompt 
character, 

!300;t,DX #02 

00/03GC- A2 02 LDX #02 

! LDA C,X 

00/0302- B5 00 IDA 00, X 

! 3TA $10, X 

00/03CS- 95 10 STA 10, X 

I DEX 

00/0306- CA DEX 

! STA SC03Q 

00/0307- BO 30 CO STA C030 

! BPL S302 

00/030A- 10 F€ BPL 0302 

I BRK 00 

00/030C- Cd 00 BRK 00 

<• Note; Don't forget the space after the exclamation poinL The program needs the 
space after the exlamation point to follow the address precedent set by the initial 
instruction. 
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If you want lo enter a program in hexadecimal notation, you must start in the hex 
mode f as the following example indicates; 

! 1000s J23 24 25 
tfiO 61 CI 

If an instruction line has an error in it, the mini -assembler beeps loudly and displays a 
caret (~) under or near the offending character in the input line, If you forget the space 
before or after a mnemonic or include an extraneous character in the hexadecimal 
value or address, the mini -assembler rejects the inpui line. If the destination address 
of a branch instruction is out of the range of the branch (more than 127 locations 
distant from the address of the instruction), the mini-assembler flags this as an error. 

To leave the mini-assembler and reenter the Monitor, press Return immediately after 
the ! prompt. 

Your assembly-language program is now stored in memory. You can display it with 
the List (L) instruction as follows: 






•3od: 










l=m 1- 


I 


l=LCBa 


nkCO/1) 




00/0300- 


A2 


02 


LOX 


#02 


00/0302- 


as 


00 


LDA 


00, X 


00/0304- 


:>: 


10 


STA 


" :: . :■: 


00/0306- 


CA 




DEX 




00/0307- 


8D 


30 CO 


STA 


C030 


so/aaDA- 


ia 


Ffi 


BPL 


0302 


D0/O3OC- 


00 


00 


BRK 


00 


::o •::.;::?: 


00 


00 


-! -' 


00 




00 

i 9 


M 

00 


3RK 
BBK 


DO 
00 


M/033.4.- 


00 


00 


BRK 


00 


00/0316- 


00 


30 


BRK 


B0 


00/0318- 


00 


00 


BRK 


D 


00/031A- 


00 


: o 


BRK 


.... 



(After ihc Droaram is displayed ih<> l.faf InrfnirUftn 
displays enough lines ofcode to fill the screen.) 
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Mini-assembler instruction formats 

The mini-assembler recognizes 256 mnemonics and 24 addressing formats. Table 3-7 
shows the address formats for the 65C816 assembly language. (Mini-assembler 
opcodes are listed in Appendix F, " Disassembler/Mini-Assembler Opcodes.") 

Tabid 3-7 

Mini-assembler address formats 



Mode 


Nam* 


Formal 


a 


Absolute 


1234 


a,x 


Absolute indexed (with x) 


1234,X 


a.y 


Absolute indexed (with y) 


1234.Y 


(a,x) 


Absolute indexed indirect 


(1Z34.X) 


al.x 


Absolute indexed long 


081234.X 


(a) 


Absolute indirect 


(1234) 


al 


Absolute long 


081234 


Ace 


Accumulator 


Blank 


xy:i 


Block move 


01,02 


d 


Direct 


45 


d,x 


Direct indexed (with x) 


45,X 


d,y 


Direct indexed (with y) 


45.Y 


<d.x) 


Direct indexed indirect 


(45.X) 


(d) 


Direct indirect 


(45) 


(d),y 


Direct indirect indexed 


(45),Y 


ld],y 


Direct indirect indexed long 


[451, Y 


[d] 


Direct indirect long 


[451 


# 


Immediate 


#23 or #2345 


i 


Implied 


Blank 


r 


Program counter relative 


1000 1+50} 


r. 


Program counter relative long 


1000 1-0200} 


s 


Stack 


Blank 


r,s 


Stack relative 


10.S 


(r,s),y 


Slack relative indirect indexed 


(10,S>,Y 



An address consists of one or more hexadecimal digits. The mini -assembler 
interprets addresses the same way the Monitor does: If one, three, or five digits are 
entered, a preceding zero is automatically entered as well. For example, the 
instruction LDA *1 is assembled as A9 0L 

♦ Note; The dollar signs ($) used in this manual to signify hexadecimal notation are 
ignored by the mini-assembler and may be omitted when typing programs, 
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Branch in$iru€tiom which use ifae relative addressing mode, require the target 

address of the branch. The mini-assembler automatically calculates the relative 
distance to use in the instruction. If the target address is more than the allowable 
distance from the current program counter, the mini-assembler sounds a beep, 
displays a caret (*) under the target address, and does not assemble the line. 

If you give the mini-assembler the mnemonic for an instruction and an operand and 
the addressing mode of the operand cannot be used with die instruction you entered, 
the mini-assembler will not accept the line. 



The Apple IIGS tools 

As you are creating a program, you will very likely want to incorporate calls to various 
Apple ITgs tools into your program. To use the tools, you need an intimate knowledge 
of the tools themselves. You should therefore consult the appropriate Apple IIGS 
Toolbox Reference manual for information about each tool. The Monitor includes a 
Toot Locator call as one of the commands. The format and details are given in the 
command summary at the end of this chapter. 

The Tool Locator command actually performs a call to the selected tool, performs the 
desired function, and provides you with debug information about the data that the tool 
provides as retu rn values. 

The Tool Locator call lets you type a one-line command instead of requiring that you 
create a program to test the tool. See the Apple IIGS Toolbox Reference for more 
information, 



The disassembler 

Because hexadecimal code is so difficult to read and understand, you may want to 
translate machine language back into assembly language. You can use the list 
instruction as a disassembler for this purpose. 

The Monitor List instruction has the format 

(start address \L 

The List instruction starts at the specified locaUon and displays a full screen (20 tines) 
of instructions, For example, if you want to display a list of instructions starting at 
location Si 000 in bank 12, type 

•12/1000L Return 
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The following list is displayed: 



0»m 0- 


-x 


t^LCBar.k 


(0/1) 




12/1000 


AO 


IS 


Lfl 


LDA 


1815 


12/1003 


93 


50 


10 


STA 


1050, X 


12/1006 


9F 


50 


52 05 


STA 


055250 


12/10QA 


A9 


7"? 


66 


LOA 


16677 


12/100D 


82 


20 


Lfl 


BRL 


2030 1+1020} 


12/1010 


80 


20 




BRA 


icm i*aoj 


12/1012 


F4 


L2 


14 


PEA 


3412 


12/1015 


52 


10 


10 


PES 


2028 


12/1018 


87 


45 




STA 


[45] 


12/101A 


62 


DO 


FO 


PER 


001D (-10001 


12/101D 


A9 


23 




LDA 


#0023 


12/101F 


A2 


45 


67 


LDX 


#6745 


12/1022 


-IF 


H 


46 02 


GOB 


0244654 


12/1026 


DC 


89 


23 


-y.: 


(2389) 


12/1029 


7C 


BE 


n 


J5R 


(F2BE,X» 


12/102C 


'3 


i q 




ADC 


(40,S),Y 


12/102E 


CI 


06 




CMP 


(06),Y 


12/1030 


0A 






A5L 




12/1031 


00 


23 




BRK 


23 


12/1033 


BB 






CLV 





The top line of the disassembly shows you (he current settings of the m and x bits of the 
65C816 status register. Recall that you set these bits by using the { val) =m and { vol] =x 
Monitor commands. Both affect the way the disassembly is performed by the 
Monitor. The LC (language-card) bank information shows you which of the two 
available language-card banks is currently active. You change [he language-card bank 
by using the ( val\ =L command. 

The disassembler can disassemble all 65C816 opcodes in emulation and native modes 
(both &-bil and 16-bit native mode). In either native or emulation mode, the sizes of 
the accumulator and index registers are significant. In immediate mode, the sizes are 
important for the opcodes listed in Table 3-8. 
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Display Memory Location 

\from_ address \ 

Displays contents of memory location as 
[from address } : [ vol) - 1 ASCII] 

Display a Range of Memory Locations 

{from address) , | to address \- 

Displays memory. 

In 40-column mode, type 

*20/401.413 

Memory contents from $0401 in bank 20 to $0413 in bank 20 are displayed in 
40-column mode: 

20/04 01: CI C2 C3 C4 C5 C6 C7-ABCDEFG 
2Q/0'iOB:C8 C9 CA CB CC CD CE CF-HIJKLMN0 
20/0410:00 Dl 02 03-PQ. 

In 80-column mode f type 

"20/401.42 

Memory contents from $0401 in bank 20 to $0413 in bank 20 are displayed in 
80-column mode: 

20/04D1:C1 C2 C3 Cr, C5 C6 C7 C8 C9 CA CB CC CD CD CF-ABCDEFGHI JKOLMN0 

410;D0 Dl 02 03 04 05 06 07 D2 D3 D4 D5 D€ Ot Dfl D9-PQ HSTUVWXY' 

20/04 20: El E2-abed 

♦ Note: Printable ASCII characters are output as norma! ASCII characters. 

Nonprintable characters are oulpul as periods. In 40-column mode, half a page of 
memory can be displayed, in 80-column mode, a full page of memory can be 

displayed. 

Terminate Memory Range 
Corurol-X 

Terminates Display Range of Memory Locations command. 
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Carriage Return 

Return 

Performs a carriage return wiih no preceding entry. 

In 40-column mode, displays the contents of up to the next 8 locations in hexadecimal 
*nd ASCII formats. CLocation starts at last [bank/ address } entered and continues 
until the low nibble of the addresses being displayed equals or 8.) See format of 
Display Memory Location command. 

In 80-column mode, displays the contents of up to the next 16 locations in 
hexadecimal and ASCII formats, (Location starts at the last ( bank/ address) 
a-.k-rrd and continues until the low nibble of the addresses being displayed equals 0, i 

See format of Display Memory Location command. 

Move, M 

{ destination | < [from_addm$$) . { toaddress} H 

Moves data from \from_address ] through \to_addre$s\ to locations starting at 
( destination \ . 



»,v 



{destination ■ < i.from_addre&s) , \ to address) v 

Compares the memory contents starting at {destination} through 

[destination] +{{t0_address - {from_a4dre$s}) with the memory contents starting 

at \from_address\ through \to_address) and verifies thai they are the same. 

Rll Memory, Z 

\vaii<i from address) . \ to_address • :■■' 

Fills memory in the range {from_address \ through [toaddress] with the 1-byte 
value [val). 

Pattern Search, P 

Vfintfl) {• literal ASCII" J | • i23f I | tw&l \< [from address) . I to address] P 

Searches for any length pattern up to 236 bytes in memory ranging from 
[from_address] through { to__address) -, [vat\ can be hexadecimal, literal ASCII, or 
Hipped ASCII. The address of each location where the pattern is found is output to the 
screen followed by a carriage return, The pattern search continues until the entire 

range of addresses has been examined. 
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Examine Registers 
Gontrol-E 

Examines 65C816 registers and flags. 
The screen displays 

A=aaaa X=xxxx Y-yyyy S-sass D-dddd P-pp 
B-bb K— 5ck M-mm Q«qq L»l m"m x=-x e=e 

On a 40-colurnn screen, two lines are displayed automatically; on an 80-eolumn 
screen, only one line is displayed. 

Change the A Register, A 

I vail 6) =A 

Changes A register value to {vall6l for Resume/Go/F.xecute/Step/Trace commands 
Note- A must be uppercase. 

Change X Registei, X 

{valid) -X 

Changes X register value to \vatl6) for Resume/Go/ExecuLe/Slep/Trace commands. 
Note: X must be uppercase. 

Change Y Register, Y 

\val!6^=i 

Changes Y register value to \vall6) for Resume/Go/Execute/Step/Trace commands. 
Note: Y must be uppercase. 

Change D Register, D 

vain- 

Changes direct-page/zcro-page register value lo { vol 16} for 
Resume/Go/Execute/Step/Trace commands. Note: D must be uppercase. 
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I Change Data Bank Register, B 



Changes data bank register value to [val] for Resume/Go/Execuie/Siep/Trace 
commands. Note: B must be uppercase. 

Change Program Register, K 

[wfi-K 

Changes program register value to (val) for Resume/Go/Execute/Siep/Trace 
commands. Note: K must be uppercase. 



Change Sfack Pointer, s 

Changes stack pointer value to {vail 6] for Resume/Go/Execuie/Sicp/Trace 
commands. Note: S must be uppercase. 



Change Processor Siatus, P 

fnafi-s 

Changes processor status value to [val] for Besume/Go/Execule/Slep/Trace 
commands. Note: P must be uppercase. 

Change Machine State, M 

Changes machine-state value to \val\ for Resume/Go/Execule/Slep/Trace 
commands. Note; M must, be uppercase. 

The M biLs arc as follows: 

Bit 7 = 1 Makes alternate ^ero page/LC active 

Bit 6 ■ 1 Makes Page 2 active 

Bit 5 - 1 Makes RAMRD active 

Bit 4 = 1 Makes RAMWRT active 

Bit 3 = 1 Makes RDLCROM active, not read/write — read only 
Bit 2 « 1 Makes LC bank 2 active 
Bit 1 = 1 Makes alternate ROMBANK active- 
Bit = 1 Makes INTCXROM active 



Summary of Monitor Instructions 
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Change Quagmire Stafe, Q 

Changes Quagmire state value to ( vat] for Resume/Go/Exeeuie/Step/Trace 
commands. (The Quagmire value controls shadowing and system speed). 
Note. Q must be uppercase. 

The Q bits are as follows: 

Bit 7 = 1 High speed 

Bii 6 • 1 Slops IOLC shadowing 

Bii 5 = Always must be 

Bit 4 = 1 Stops auxiliary- memory Hi-Res shadowing 

Bit 3 ■ 1 Stops Super Hi-Res shadowing 

Bii 2 = 1 Slops 1 li-Res Page 2 shadowing 

Bit 1 = 1 Stops Hi-Res Page 1 shadowing 

Bit = I Stops text Page 1 shadowing 



Change Accumulator Mode, m 

\ vol) =o 

Changes accumulator mode value lo {val\ for Resume/Go/Execute/Step/Trace/List 
commands. Note: m must be lowercase, 

= 16-bit mode 

1 ■ 8-bit mode 



Change Index Mode, x 

f val)-x 

Changes index mode value to { vat] for Resume/Go/Execute/Step/Trace/List 
commands. Note: x must be lowercase. 

= 1 6-bit mode 

1 - 8-bit mode 

Change Emulation Mode, e 

\vat\ -e 

Changes emulation-mode value to \val\ for Resume/Go/Execute/Step/Trace/lisl 
commands. Note: e must be lowercase. 
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Cheng e Language- Card Bank, L 

Changes language-card bank value to [val) for Resume/Go/Execute/Stcp/Trace/'List 
commands. Note: L must be uppercase. 

= First bank of language card 

1 ■ Second bank of language card 

Change Filter Mask, F 

\ vat) =f 

Changes the ASCII filter mask value to { val) For mini-assembler ASCII entry and 
Monitor ASCII Lm mediate-mode commands, The ASCD niter is \NDed with aJI am n 
characters entered in the Monitor. Affects both data entry and search conditions. Any 
value from $00 to SFF is valid. Note: F must be uppercase. The default value is FF. 

Change Text Display, I (Inverse) 

►Switches to inverse video text display. Note: I must be uppercase. 
Change Text Display, N (Normal) 
L 

Switches to normal video text display. Note.- N must be uppercase. 
Display Time and Date, T 

Displays current lime and date. Note: T must be uppercase. 
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Change Time and Dote 

^l^nn/dd/yy hhimmiss 

Changes time. Note: T must be uppercase. Any delimiter except an apostrophe- (•) 
may be used between values entered. 

Enter 



hh = hours 


0-23 


mm * minutes 


0-59 


55 = seconds 


0-59 


mi = month 


1-12 


dd ■ day 


1-31 


yy - year 


0-99 


Redirect input Links, K 


\slot) Conirol-K 




Redirects input J 


inks to [slot] 



Redirect Output Links, P 

: slot] Control-P 

Redirects output links to [slot). 

Change Consecutive Memory 

{ bank/ address \:(val\ i vah ( ws/ 1 {'• literal ASCII" J \ "flip ASCII' 



vat. 



Changes consecutive memory locations starting at [ bank/ address) to the values after 
the colon (:). Values can be in hex, literal ASCII, or flip ASCII formal. 

Change Screen Display, T 
Control -T 

Changes screen display to text Page 1, regardless of current soft-switch settings. 

Change Cursor 

Control-* \ character) 

Changes the cursor to a [character] symbol. This command is implemented through 
COUT1 and C3COIJT1. It is not an input command; it works only through the BASIC 
output links. If (character) is the Delete character, the original cursor is restored. 



C 
{i 

G 

m 
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Convert Hexadecimal to Decimal Format 

ltal64\= Return 

JwwertS hexadecimal number entered to decimal number (8-digit hex number 
maximum) Result is primed starting at first column on next line. 

>nvert Decimal to Hexadecimal Format 

himlW! Return 

Converts decimal number entered to hexadecimal number (10-digit decimal number 
maximum). Result is printed starting at first column on next line. Entries may be 
signed (+/-) or unsigned. 

Jump to Cold Start 

tontsol-fi 

Jnconditionalty jumps to BASIC'S cold-start routine at ROM location 5F.00Q, 

Jump to Warm Start 

Control C 

Unconditionally jumps to BASIC'S warm-start routine at ROM location SE003. 

Jump to User Vector 

Cootrol-Y 

Unconditionally jumps to user vector at S03F8. 

Quit Monitor, Q 

Jiseontinues Monitor operation. Unconditionally jumps to S3D0 to warm-start the 
-erating system. 



c Program in Bank $00, G 

■ \swl_address}G 

I Transfers control to the machine-language program beginning at {start_addmss\ . 

RSets die environment from stored locations A/X'Y/S/D/P/B/K/M/Q/L/m/x/e ; 
pushes RTS information on the user's slack and performs a JMP to { slart_address\ 
with RTS informau'on left on the stack (only works for code in bank $00 because ii 
assumes user's routine ends in an RTS). 

Summary of Monitor Instructions 
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Reset the Environment and Transfer Control, X (Execute) 

i start address )X 

Retrieves A/X/Y/S/D/P/B/K/M/Q/L/m/x/e data from stored locations, sets those 
data as the environment, pushes RTL information on the user's stack, and perforins a 
JMP to \statt_address} with RTL informaUon on the stack (works for code in any hank; 
assumes user's code ends in an RTL). 

Restore Registers and Flags 

r.onlrol-K 

Restores registers and flags to the normal Monitor configuration mode Changes 
A/X/Y/S/D/P/B/K/M/Q/L/m/x/e. 

Reset !he Environment and Transfer Control. R (Resume) 

'. star(address) R 

Sets the environment from stored locations A/XA r /S/D/P/B/K/M/Q/Um/'x/e and 
jMPs to {stan_address}. 

Perform a Program Step, S 

I star t address )'$ 

Not implemented in current version, 

Perform a Program Trace, T 

f start address \ r 

Not implemented in current version. 

Disassemble, L (List) 

[s[art_adcltvss]L 

Disassembles up to 20 instructions starting at location {start address}. 
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Tool Locator, U 

Mbytes So stkjt bytes frm stk parml _, . .parmzj'unction^ tooftw 

The underline character (_) indicates where spaces must be placed 

I bytes to stk indicates the number of parameters that need to be pushed onto the stack 
to make the utility call to the specified tool. 

I bytes f mi stk indicates the number nt parameters the funcu'on pushes onto the stack. 
That many byies will be pulled from the stack and displayed at the end of the call. 

parml_. . .parmz indicates the parar i push onto the stack before making ihe 

Tool locator call. Parameters must be single-byte values. For example, to enter a 
4-byte address, type 00 bb hh 11, where 

DC = null byte of address (space required after byte) 

bb = bank number of address (space required after byte) 

hh = high byte of address (space required after byte) 

II = low byte of address space (space required after byte, before next parameter) 

To enter multiple ASCII bytes, type 'W, 'X 1 or "w", "X", using cither single or 
double quotation marks. Each ASCII byte is a parameter and so must be separated v 
i space. 

function* indicates the function number to be called in the specified tool, 
tool* indicates the tool number to be called by utility ..ill 

The function numbers and tool numbers are listed in ihe Apple UGH Toolbox 

Reference ; 

A tool error number is always primed along with parameters left on the stack after the 
tool is called. The formal of the error printout is Tool error = eeee, where eeee is 
the value of the accumulator (error) after the tool call. On errors SO00l-$0OOF, the U 
command removes and displays exactly the number of bytes it pushed onto the stack 
before the call. For errors >$000l ; . no parameters are left on the stack, SO none 
displayed. 
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ITiis chapter describes the routines and command sequences that you use to control 
the video output of text to the Apple IIGS video screen. The Apple IIGS video firmware 
includes routines for icxi input and output. These routines are used by high-level 
languages, but can just as easily be called directly from a routine that you have written 
using the mini -assembler. Almost every program on the Apple IIGS takes input from 
the keyboard or mouse and sends output lo die display. The Monitor and BASIC 
accept keyboard input and produce screen output by using standard inpul/outpul 

■- •- « .1 r - - — -« • i 

(I/O) subroutines built into the Apple IIGS firmware. 
Using the video firmware I/O routines, you can 
d read keys individually From the keyboard 

□ read an entire line of key et 

G send characters to the Firmware output routines 

□ call buik-in routines that control the video display 

When you call a routine to get an entire fine, the user has the opportunity to use the 
Backspace key and other onscreen editing facilities before wast routine sees the line. 
When you send characters to the firmware output routines, most oFlhe characters are 
transmitted to the display. However, some of the characters control the display 
subsystem. These special characters are listed in Tables 4-1, 4-3, and 4-4. 



Standard I/O finks 

When you call one of live character I/O subroutines (GOUT and RDKEY), the video 
firmware performs an indirect jump to an address stored in programmable memory. 
Memory locations used for transferring control to other re sometimes 

called vectors; in mis manual, the locations used for transFerring control to the I/O 
subroutines arc called I/O links. In an Apple IIGS running without a disk, each I/O link 
normally contains the address oF the body of the subroutine CCOUT1 or KEYIN) that 
the firmware calls for that specific form of I/O If a disk operating system is running, 
one or both of these links holds the address of the corresponding DOS or ProDOS I/O 
routines instead of die firmware default values. (DOS and ProDOS maintain their own 
links to the standard I/O subroutines.) 

By tailing (he I/O subroutines dial jump to the link addresses instead of calling the 
stand i routines directly, you ensure thai your program will work properly with 

other software, such as DOS or a printer driver, that changes one or both of the I/O 
links. 

For the purposes of ihis chapter, we shall assume thai the I/O links contain the 
addresses oFthe standard I/O subroutines: COUTl and KEVIN iF the 80-column 
firmware is disabled, and BASICOIJT (also called C3GOUT1) and UASICIN if die 

80-co!umn Firmware is enabled. 
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Star 

The A 

kcybc 

input 

one c 

n 

readk 

subro 

RDKL" 

GETL 

RDK 

Your 

l-OKl 
to fla. 
subrc 

RDK1 
the c 
curse 
that | 
next 
reel* 

KE\ 

App 

Inac 
subf 
acct 

II il' 
che' 
thei 
disf 
moi 
indi 
cha 




Standard input routines 

The Apple HGS firmware includes three diffcreni subroutines for reading from the 
keyboard. These subroutines are written to function at different levels. The character 
input subroutine KEYIN (or BASIC1N when the 80- column firmware is active) accepts 
one character at a lime from the keyboard. The RDKEY subroutine (short for 
Mdkey) calls KEYIN or BASICIN and handles the onscreen cursor. The third 
subroutine is named GETLN, which stands for get line. By making repeated calls to 
RDKEY, GETLN accepts a sequence of characters terminated with a carriage return. 
GETLN also provides onscreen editing features. 



RDKEY input subroutine 

Your program gets a character from the keyboard by making a subroutine call to 
RDKEY at memory location $FD0C, RDKEY sets the character at the cursor position 
50 flash and then passes control through the input link KSW to the current input 
subroutine, which is normally KEYTN or BASICIN. 

RDKEY produces a cursor at the current cursor position, immediately to the right of 
the character you last sent to the display (normally by using the COUT routine). The 
cursor displayed by RDKEY is a flashing version of the character thai happens to be at 
Ihat position on the screen. Usually, a user types new characters on a blank line, so the 
next character will normally be a space. Thus, the cursor appears as a blinking 
rectangle. 



IN and BASICIN input subroutines 

Apple IIGS supports 40- and 80-column video displays by using input subroutines 
KEYIN and BASICIN, The KEYIN subroutine is used when the 80-column firmware is 
Inactive; BASICIN is used when the 80-column firmware is active. When called, the 
subroutine wails until the user presses a key and then returns with the key code in the 
accumulator. 

If the 80-column firmware is inactive, KEYIN displays a cursor by storing a 
checkerboard block in the cursor location, then storing the original character, and 
then storing the checkerboard again. If the 80-column firmware is active, BASICIN 
displays a steady inverse space (rectangle) as a cursor. In an additional operating 
mode, escape mode, the cursor displayed is an inverse video plus sign (+). This 
Indicates that escape mode is active. See the section "Cursor Control" later in this 
•^Chapter for more information about the escape mode. 
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Subroutine KEYIN also generates a random number. While il is wailing for the user to 
press a key, KEYIN repeatedly increments the 16 -bit number in memory locations 78 
and 79 (hexadecimal $4E and $4F). This number continues to increase from to 65535 
and then starts over again at 0. The value of this number changes so rapidly that there 
is no way to predict what it will be after a key is pressed A program that reads from the 
keyboard can use this value as a random number or as a seed for a random-number 
generator. 

When the user presses a key, KEYIN accepts the character, stops displaying the cursor, 
and returns to the calling program with the character in the accumulator. 

Escape codes 

Subroutine KEYIN has special functions that you invoke by typing escape codes at the 
ard. An escape code is obtained by pressing the Esc (Escape) key, releasing it, 
and then pressing another key. The key sequences shown are not case sensitive. That 
is, Esc followed by A (uppercase) is equivalent lo Esc followed by a (lowercase). 

Escape codes are used to clear the current line, the rest of the screen, or the whole 
screen; to switch from 40-column to 80-column mode and vice versa; and to move ihe 
cursor on the screen. The escape codes that KEYIN follows are listed in Table 4-1, 

Cursor control 

The Apple IIGS is equipped with four arrow keys. However, these keys do not perform 
cursor-movement functions unless the system is specifically told to give diem such 
functions. The Apple IIGS firmware provides what is called the escape mode, which 
activates the arrow keys for cursor moves. One of eight possible escape sequences can 
be used to activate the escape mode. As Table 4-1 shows, you can enter escape mode 
by pressing Esc followed by an alphabetic key or by pressing Esc followed by one of the 
four arrow keys. Recall also dial when the 80-column firmware is active, the cursor 
display changes to a plus sign (+) when the system is operating in escape mode. 

You can continue to use the arrow keys to move around on the screen. As noted in the 
table, escape mode terminates when anything other than an arrow key is pressed. 
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Tobl«4-1 

Escape codes and their functions 



Escape cod* 



Function 



Cursor control 
Esc A 

EscB 

ESCC 

!,,: D 

Cursor control/ 

entering escape mode 

EscI 

(or Esc Up Arrow) 

Ek I 

(or Esc Left Arrow) 

EscK 

(or Esc Right Arrow) 

EscM 

(or Esc Down Arrow) 

Screen/line clearing 
Esc® 

EscE 

E5CF 

Screen format control 
Ek4 



Est E 

Esc-Control-D 

Esc-Control-E 
Esc-Control-Q 



Moves cursor right one space; exits from escape mode 
Moves cursor left one space-, exits from escape mode 
Moves cursor down one line; exits from escape mode 
Moves cursor up one line; exits from escape mode 

Moves cursor up one line and remains in escape mode 
Moves cursor left one space and remains in escape mode 
Moves cursor right one space and remains in escape mode 
Moves cursor down one line and remains in escape mode 

Clears window and moves cursor to its home position 
(upper-left corner of screen); exits from escape mode 

Clears to end of line; exits from escape mode- 
Clears to bottom of window; exits from escape mode 

Switches from 80-coIumn display to 40-column display if 
80-column firmware is active, sets links to BASICIN and 
BASICOUT, restores normal window size; exits from escape 

mode: 

Switches from 40-coJumn display !o 80-column display by 
enabling 80-column firmware, sets links to BASICIN and 
BASICOUT, restores normal window size; exits from escape 
mode 

Disables control characters; only carriage returns, line 
feeds, bells, and backspaces have effects when printing is 
performed 

Reactivates control characters 

If 80-column firmware is active, deactivates 80-column 
firmware, sets links lo KEY1N and COUT1, restores normal 
window size, exits from escape mode 

Standard Input routines 
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GETLN input subroutine 

Programs often need strings of characters as input. Although you can call RDKEY 
repeatedly lo get several characters from the keyboard, there is a more powerful 
subroutine you can use to gel an edited line of characters. This routine is named 
G'/'VLV, which stands for get line; GETLN starts at tocaiion SFDoA. Using repeated calls 
to RDKEY, GETLN accepts characters from the standard input subroutine — usually 
KEY1N — and puts them into the input buffer located in the memory page from $200 to 
S2FF. GETLN also provides the user with onscreen editing and control features. These 
are described in the next section, "Editing With GETLN." 

GETLN displays a prompting character, called a prompt. The prompt indicates lo the 
user that the program is waiting for input. Different programs use different prompt 
characters to help remind the user which program is requesting input. For example, 
an INPUT statement in a BASIC program displays a question mark (?) as a prompt. 
The prompt characters used by Apple IIGS programs are shown in Table 4-2. 

GETLN uses the character stored at location 51 (hexadecimal S33) as the prompt 
character. In an assembly-language program, you can change the prompt to any- 
character that you wish. In BASIC or in the Monitor, changing the prompt character 
has no effect because both BASIC and the Monitor restore the prompt to their original 
choices each time they request user input. 

Table 4-2 

Prompt characters 



Prompt 
character 



Program requesting Input 



J 

> 

* 



User's BASIC program (INPUT statement) 

Applesoft BASIC 

Integer BASIC 

Monitor 

Mini-assembler 



As you type an input character string, GETLN sends each character to the standard 
output routine, normally COUT1, which displays the character at the previous cursor 
position and puis the cursor at the next available position on the display, usually 
immediately to the right of the original position. As the cursor travels across the 
display, it indicates the position where the next character will be displayed 

GETLN stores the characters in its buffer, starting at memory location S200 and using 
the X register to index the buffer. GETLN continues to accept and display characters 
until you press Return. Then it clears the remainder of the line the cursor is on, stores 
the carriage return code in the buffer, sends the carriage return code to the display, 
and returns to the calling program, 
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The maximum line length thai GETLN can handle is 255 characters. If the user types 
more than 255 characters, GETLN sends a backslash (\) and a carriage return to the 
display, cancels the line it has accepted so far, and starts over. To warn the user that 
the line is gelling full, GETLN sounds a bell (tone) at every keypress after the 2-igth, 

Editing with GETLN 

The subroutine GETLN provides Lhe .s!;mdard onscreen editing features used with 
BASIC interpreters and the Monitor. Any program that uses GETLN for reading the 
keyboard offers these features. For an introduction to editing with GETLN, refer to lhe 
Applesoft Tutorial. 

Cancel line; Any rime you are typing a line, pressing Conttol-X causes GETLN to 
cancel the line. GETLN displays a backslash (V) and issues a carriage reiurn and then 
displays Lhe prompt and waits for you to type a new line. GETLN automatically cancels 
the line when you type more than 255 characters, as described earlier. 

Backspace: When you press trie Backspace key, the Back Arrow key («-), or the Delete 
key, GETLN moves its buffer pointer back one space, deleting the last character in its 
buffer. It also sends a backspace character to the routine COUT, which moves the 
display position back one space. If you type another character now, it will replace the 
character you backspaced over, both on the display and in the tine buffer. Each time 
you press the Backspace key, the cursor moves left and deletes another character until 
you reach the beginning of the line. If you then press Backspace one more time, you 
cancel the line. If the line is canceled this way, GETLN issues a carriage return and 
displays the prompt, 

Jtalype: The function of the Retype key (->) is complementary to the function of the 
Backspace key. When you press Retype, GETLN picks up the character at the display 
position just as if it had been typed on the keyboard. You can use this procedure to 
pick up characters that you have just deleted by backspacing across them. You can use 
the backspace and retype functions with the cursor-motion functions to edit data on 
the display. For more information about cursor motion, sec the section "Cursor 
Control" earlier in this chapter. 



Keyboard input buffering 

In versions of the Apple 11 prior to the Apple IIGS, if a user pressed a key while a 
program was processing the previous keystroke, characters that the user was typing into 
the program were in danger of being lost. The Apple IIGS allows you to use keyboard 
input buffering to prevent the loss of keystrokes. 

The user can select keyboard input buffering through the Conirol Panel program. IF the 
Event Manager is enabled, the type-ahead buffer can process an unlimited number of 
key presses. 
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Standard output routines 

The Monitor Firmware output routine is named COLT (pronounced C-oui), which 
stands for character out > The COUT routine normally calls COUTH, which sends one 
character to the display, advances the cursor position, and scrolls the display when 
necessary. The COUT1 routine restricts its use of the display to an active area called 
the text window, described later in this chapter, 

BASICOUT is used instead of COUT1 when the 80-column Firmware is active. 
Subroutine BASICOUT is essentially the same as COTJT1: BASICOUT displays the 
character in the accumulator on the display screen at the current cursor position and 
advances the cursor. When BASICOUT returns control to the calling program, all 
registers are intact 



COUT and BASICOUT subroutines 

When you call COUT (or BASICOUT) and send a character to COUT1, the character is 
displayed at the current cursor position, replacing whatever was there. COUT1 then 
advances the cursor position one space to the right- If the cursor position is at the right 
edge of the window, COLT1 moves the cursor to the leftmost position on the next line 
down. If this moves the cursor past the end of the last line in the window, COUT1 
scrolls the display up one line and sets the cursor position at the left end of the new 
bottom line. 

The cursor position is controlled by the values in memory locations 36 and 37 
(hexadecimal $24 and $25)- Subroutine COUT! does not display a cursor, but the 
input routines COUT1 and C3COUT1, described in the next section, do display and 
use a cursor. If another routine displays a cursor, that routine will not necessarily put 
the character in the cursor position used by COUT!. 

Control characters with COUT1 and C3COUT1 

Subroutine COUT1 is the entry point that is active for character output in 40-column 
mode. Entry point C3COUT1 is active when the system is in 80-column mode, 
Subroutines COUT1 and C3COUT1 do not display control characters. Instead, the 
control characters listed in Tables 4-3 and 4-4 are used to initiate action by the 
firmware. Other control characters are ignored. Most of the functions listed here can 
also be invoked from the keyboard, either by typing the control character listed or by 

u.iLiu m.'uirunvu uiyili Li.v ivvj-rt/Ju, Mul" tj'f VJ ping \i»V *.*■>• luui "CI laiai.n.'T a»J».«_il w. ii j 

using the appropriate escape code, as described in the section "Escape Codes" earlier 
in this chapter. 
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Tab Is 4-3 






Control characters with BO-column firmware off 




Control character 


Action taken by couti 


Control-G 


Produces user-defined tone (Control Panel menu? 


Control-H 


Causes backspace 




Conlrol-J 


Causes line feed 




1 Contral-M 


Causes carriage return 




1 Cootra(-A [char] 


First character output after Control- a becomes new cursor. If 
Delete key is first character, default prompt Is restored. 




Tabl« 4-4 






1 Control characters with BQ-column firmware on 




Control character 


Action lake.-, by C3COUT1 


1 Control- E 


Turns cursor off 


1 Control -F 


Turns cursor on 




1 Control -G 


Produces user-defined tone (Control Panel menu) 




1 Canlrol-H 


Causes backspace 




I Control-J 


Causes line feed 




1 Conlrol-K 


Clears from cursor position to end of screen 




1 Contiol-L 


Causes form feed 




1 Cantrol-M 


Causes carriage return 




1 Control-N 


Changes to normal display format 




1 Conirol-O 


Changes to inverse display format 




1 Conttol-Q 


Sets 40-column display 




1 Control-R 


Sets 80-column display 




1 Conuol-S 


Stops listing of characters until another key is pressed 




[ Control- U 


Deactivates enhanced video firmware 




1 Control-V 


Scrolls display down one line, leaving cursor in current position 




1 Control -W 


Scrolls display up one line* leaving cursor in airrem position 




1 Control-X 


Disables MouseText character display and uses inverse 
uppercase characters 




1 Conirol-Y 


Homes cursor to upper-left corner 




1 Control -Z 


Clears line on which cursor resides 




1 Conuol-l 


Enables MouseText character display by mapping inverse 
uppercase characters to MouseText characters 




1 Control- N 


Moves cursor position one space to right; from edge of window, 
moves to left end of next line 




1 Control-! 


Clears from cursor position to right end of line 




1 Control-. 


Moves cursor up one line with no scroll 




1 Control** 


Goes to XY- using next two characters minus 32 as 1-byte X and Y 






values, moves cursor to CH=X, CV=Y (Pascal) 


1 Control- a [char] 


First character output after Control- A becomes new cursor. If 
Delete key is first character, default prompt is restored. This 
works only when using BASIC links, not Pascal output links. 
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Inverse and flashing text 

Subroutine COUT1 can display lext in normal format, inverse Format, or with some 
restric Lions flashing format. The display format for any character in the display 
depends on two factors: the character set currently being used and the setting of the 
two high-order bit.* of the character's byte in the display memory 

As it sends your text characters to the display. COUT1 sets the high-order bits 
according to the value stored at memory location 50 (hexadecimat S32), If that value i-s 
255 (hexadecimal $FF), COUT1 sets the character display to normal format- If that 
value is 63 (hexadecimal S3F), COUT1 sets the character display to inverse formal. If 
the value is 127 (hexadecimal $7F) and if you have selected the primary character set, 
the characters wil! be displayed in flashing format. Note that the flashing format is not 
available in the alternate character set. Table 4-5 shows the effect of the mask value on 
particular parts of the character set. 

Table 4-5 

Text format control values 



Mask 
(dec) 



Valu* 
<hex> 



Display tormat 



255 
127 
65 



$7F 
$3F 



Normal, uppercase, and lowercase 
Flashing, uppercase, and symbols 
Inverse, uppercase, and lowercase 



To control the display format of the characters, routine COUT1 uses the value ai 
location 50 as a logical mask to force the setting of the two high-order bits of each 
character byte it puts into the display page. It docs this by performing a logical AND 
operation on the data byte and mask byte. The resulting byte contains a in any bit 
that was a in the mask. BAS1COUT, used when the 80- column firmware is active, 
changes only the high-order data bit. 

**• .vote.- If the 80-column firmware is inactive and you store a mask value at location 50 
with zeros in its low-order bits. COUT1 will mask those bits in your text As a result, 
some characters will be transformed into other characters. You should set the mask 
values only to those given in Table 4-5. 

If you set the mask value at location 50 to 127 (hexadecimal S7F), the high-order bit of 
each resulting byte will be and the characters will be displayed either as lowercase or 
flashing, depending on which character set you selected. In the primary character set, 
the next-highest bit, bit 6, selects flashing formal with uppercase characters. With the 
primary character set, you can display lowercase characters in normal format and 
uppercase characters in normal, inverse, and flashing formats. In the alternate 
character set, bit 6 selects lowercase or special characters. With the alternate character 
set, you can display uppercase and lowercase characters in normal and inverse 
formats. 
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Other firmware I/O routines 

In addition to the read and write character routines described above, the Apple FIGS 
firmware also includes several routines that provide convenient screen-oriented I/O 
functions. These functions are listed in Table 4-6 and are described in detail in 
Appendix C, "Firmware Entry Points in Bank S00." 



Important 

Appendix C Is the official list of oil entry points that are currently valid and for 
which continued support will be provided In future revisions of this product, 



Table 4-6 

Partial list of other Monitor firmware I/O routines 



Location 



Name 



SFC9C 
tFCSffi 

$FC42 

SF63n 
SI'DLD 

SFDFO 
SFDgE 
$FD8B 

SFD6A 

SK8iy 
SFC5S 

SFD1B 

$F800 

$F94A 

5FDDA 

5FDE3 

JF941 

$FDQC 

$F871 
SF864 
SFC24 



Description 



CI.REOL 
CLEOLZ 

CLREOP 

CI.RSCR 
CLRTOP 
COL IT 

CO LIT 1 

CROUT 

CROUT1 

GETLN 

HLINF 
HOME 

KEYIN 

PLOT 
PRBL2 
PRBYTE 
PSHEX 

PRNTAX 
RDKEY 

SCRN 

5ETCOL 
VTABZ 

VLIKL 



Clears to end of line from current cursor position 

Clears to end of line using contents of Y register as cursor 

position 

Clears to bottom of window 

Clears low-resolution screen 

Clears top 40 lines of low-resolution screen 

Calls output routine whose address is stored in CSW 

Cnormally COUT1) 

Displays character on screen 

Generates carriage return 

Clears to end ofline and then generates carriage return 

Displays prompt character; accepts siring of characters by 

means of RDKEY 

Draws horizontal line of blocks 

Clears window and puts cursor in upper-left corner of 

window 

With 80'Column firmware inactive, displays checkerboard 

cursor; accepts characters from keyboard 

Plots single low-resolution block on screen 

Sends 1 to 256 blank spaces to output dt 

Prints hexadecimal byte 

PrinLs 4 bits as hexadecimal number 

Prints contents of A and X in hexadecimal format 

Displays blinking cursor; goes to standard input routine 

(normally KEYIN or BASICIN) 

Reads color of low-resolution block 

Sets color for plotting in low-resolution block 

Sets cursor vertical position 

Draws vertical line of low-resolution blocks 

Other firmware I/O routines 
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The text window 

After starling the computer or after a reset operation, the firmware uses the entire 
display for text However, you can restrict text video activity to any rectangular 
portion of the display that you wish. The active portion of Lhe display is called the text 
window. COUT1 (or BASICOUT) puts characters into the window only; when ii 
reaches the end of the last line in lhe window, it scrolls only the contents of the 
window. 

You can control the amount of the screen that the video firmware reserves for text by 
modifying memory directly. You can set the top, bottom, left side, and width of the 
text window by storing lhe appropriate values in four locations in memory. This allows 
your programs to control the placement of text in the display and to protect other 
portions of the screen from being overwritten by new texL 

Memory location 32 (hexadecimal $20) contains the number of the leftmost column 
in the text window, This number normally is 0, the number of the leftmost column of 
the display. In a 40- column display, the maximum value for this number is 39 
(hexadecimal $27); in an 80-column display, the maximum value is 79 (hexadecimal 
$4P). 

Memory location 33 (hexadecimal $21) holds the width of lhe text window. For a 40- 
column display, the width normally is 40 (hexadecimal $28); for an 80-column 
display, it normally is 80 (hexadecimal $50). 

Memory location 34 (hexadecimal $22) contains the number of the top line of the text 
window. This normally is 0, the topmnsi line in the display, lis maximum value is 23 
(hexadecimal $17). 

Memory location 35 (hexadecimal $23) contains the number of the bottom line of the 
screen, lis normal value is 24 (hexadecimal $18), the bottom line of the display. Its 
minimum value is 1. 

After you have changed the text window boundaries, the appearance of the screen will 
not change until you send Lhe next character to the screen. 
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This chapter covers the features of ihe serial communications firmware. The 
Apple 1IGS serial-pori firmware provides serial communications for external devices, 
such as printers and modems. The Apple IIGS serial-port firmware uses a two-channel 
Zilog Serial Communications Controller chip (SCC8530) and RS-422 drivers. The 
driver firmware emulates the functionality of the Apple Super Serial Card C5SC) and 
supports input/output buffering as well as background printing. The firmware also 
implements a number of calls that the application can make to control the new 
features. 

Input/output buffering and background printing arc done on an interrupt basis and 
can use any buffer size up to 64K at any location that the application wishes. I/O 
I ru tiering is transparent Tor BASIC and Pascal. An application can make a function call 
that starts background printing. The function call copies the data into the background 
printing buffer and then returns control to the application. Data is fed to the printer 
automatically until the entire contents of the buffer have been sent to the printer. 

Note that AppleTalk, when active, requires the use of one of the two available serial 
.. haimc Ls Therefore, only two of these three — AppleTalk, serial port 1, and serial 
port 2 — are allowed to be active at any one time, The Control Panel program ensures 
that at least one serial port is made inactive when AppleTalk has been selected. You 
can't initialize the serial-port firmware when the channel is being used by AppleTalk. 
Both pon 1 and port 2 can be configured as either printer or communications 
(modem) ports. 

You can set default parameters for the serial ports through the Control Panel firmware. 
The application program can temporarily cliange the parameter values by sending 
control sequences to the serial-port firmware. 
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Compatibility 

The commands used to communicate with the serial-port firmware are essentially the 
same as those used with the SSC, However, many existing programs using these ports 
are not compatible with the Apple IIGS. Many programs, particularly 
communications packages, send their output directly to the hardware; the Apple IIGS 
hardware no longer uses hardware different from that used on the SSC. Print programs 
and applications written in BASIC and Pascal are more likely to work. 

One other difference between the Apple IIGS serial-port firmware and other serial- 
port firmware is in error handling. In the SSC, as well as in the Apple Sic firmware, 
when a character with an error is received, the character in error is not deleted from 
the input stream. The Apple IIGS firmware does delete the character from the input 
stream and sets a bit to record the fact that an error was encountered. 
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Operating modes 

The serial-port firmware has three main operating modes; printer mode, 
communications mode, and terminal mode. You set these modes through the 
Control Panel- An application program can change these modes by sending 
command sequences to the serial port. 

Note: If you are writing software that depends on the serial-port firmware being in a 
given operating mode, make sure that your documentation tells the user to set up 
the firmware using the Control Panel in the proper way. 



Printer mode 

When In printer mode, the serial-port firmware can send data to a printer, a local 
mal, or some other serial device. 






Communications mode 

When in communications mode, die firmware can operate with a modem. From 
BASIC, while the serial firmware is set for communications mode, the firmware can 
enter a special mode, called terminal mode, in which the Apple IIGS acts like an 
unintelligent terminal 



Terminal made 

In terminal mode, the Apple IIGS acts like an unintelligent terminal. All the characters 
typed arc pa.s.sed to iht: serial output (except the command strings), and all serial input 
goes directly to the screen. 

You enter terminal mode from the BASIC interface by typing INfrn and then typing 
the current command character followed by a T. The prompt character changes to a 
flashing underline (_\ indicating that terminal mode is active. You exit terminal 
mode by typing the current command charade r followed by a Q. 

You can use terminal mode with buffering enabled, This minimizes character loss at 
higher baud rates. Enable buffering with the Buffering Enable (BE) serial command, 
described below. 

Many remote computers send a line feed (LF) after a carriage return (CR). When using 
terminal mode with such a computer, use the Masking Enable (ME) serial control 
command to mask any line feeds that immediately follow carriage returns. 
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Handshaking 

Communications-equipment manufacturers have devised a variety of handshaking 
schemes. Apple TJgs accommodates these various schemes by providing several 
hardware and software handshaking options, 



Hardware, DTR and DSR 

When the DTR/DSR option is active, the data terminal ready (DTR) and data set ready 
(DSR) lines control the data flow into and out of the system. The Apple IIGS transmits 
characters only when the DSR line is enabled; the DTR line tells the device when the 
host is ready to accept data. The default Control Panel setting enables hardware 
handshaking. If this option is disabled, the DSR line is not checked on transmission 
and the DTR line will not be toggled during reception (see Figures 5-1 and 5-2). The 
target device's firmware determines whether these lines mean anything during data 
transfer. 

The data carrier detect (DCD) line controls modem communications. If you enable 
the DCD handshake option, the Apple lies serial-port firmware will transmit 
characters only when the DCD line is enabled The DCD option has no direct effect 
on character reception. This mode provides compatibility with the SSC, which uses 
DCD as a handshake line. 
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Figure 5-1 

Handshaking when DTR/DSR option Is turned on 
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Figure 5-2 

Handshaking when DTRyDSf? option is turned off 



Software, XON and XOFF 

If an XOFF (5 13) character is received from a device attached to the SCC, the firmware 
halts character transmission until an XON ($11) character is received. This option 
works in addition to ihe hardware handshake. In printer mode, the firmware disables 
this function. 
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Figure 5-3 

fandshaklng via XON/XO 


FF 





Handshaking 
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Operating commands 

Apple I1GS control commands, embedded in the serial output flow, are invoked by 
BASIC or Pascal output routines. For each of the operating modes (printer or 
communications), you can control many aspects of your data transmissions, such as 
baud rate, data format, and line-feed generation, by sending control codes as 
commands CO the firmware, All commands are preceded by a command character 
and optionally followed by a return character C$OD). The carriage return is allowed to 
maintain compatibility with the SSC The formal of the; commands is as follows: 

[ command-character} >, command- siring} Return 

The command character usually is Control-I in printer mode and Conirol-A in 
communications and terminal modes. In the examples in the following text, 
Control-I is used unless the command being described is available only in 
communications mode or terminal mode. A return character is represented by its 
ASCII symbol, CR. 

There are three types of command formats: 

a a number, represented by n, followed by an uppercase letter with no space between 
the characters (for example, 4D to set data format 4) 

□ an uppercase letter by itself (for example, r to reset the serial-port firmware) 

n an uppercase letter followed by either a space or no space and then either E to 
enable or D to disable a feature (for example, LD to disable automatic insertion 
of line-feed characters) 

The allowable range of n is given in each command description that follows. 

* ,Vo/e: AH options, such as baud rale, parity, and line length, can be configured 
from the Control Panel (see Chapter 10, "Mouse Firmware 1 *). 

Serial-port firmware must be reinitialized after changing options from the Control 
Panel for the new values to take effect 
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The command character 

The normal command character is Control-I (ASCII $09) in printer mode and 

itrot-A (ASCII $01} in communications mode. If you want to change the command 
character from Control-I to another command character (for example, Control-W), 
send Control-W to Control-I. To change back, send Control-I to Control-W. No 

return chancier i§ required after eiiher of these commands. 

♦ Note.- The SSC allows you to send the current command character through the 
output stream by sending the character twice in a row. The Apple IIGS does not 
allow this; the character will not be output To send the command character 
through the serial port, you must temporarily change to an alternate command 
charade r, For example, if the current command character is Control-I and you 
want to send a Control-I out the serial port, then send 

Control-] Control-A Control-I Control- A Conlrol-I 

The first two characters change the command character to a Control-A. The third 
character is the Control-I you wanted to send. 'IThe fourth and fifth characters 
restore the command character to Control-I again. Remember,, though, that you 
can disable all cornmand-character parsing by using the Zap command. 

To generate this command character in Applesoft BASIC, enter 

JRIN'T CHR$ < 9 ) ; " command-string' 

For Pascal, enter 

ISITELN [ckr < 9) , ■ command-string' } t 

The following example shows how to generate the command from a BASIC program: 



10 
JO 

!C 



DS - CHRS(fl| S 
AS - CHRS19I ; 
PRINT DS; "PR#1": 
PRINT AS; M 6B" : 



REM Sends Control-D 
REM Sands Control -I 

Establishes links BASIC to port 1 
REM Changes to 300 baud 

Continue program 



Command strings 

command string is a letter sometimes with a number prefix and sometimes with an If 
or a D suffix. Command strings select the option to be used; for instance, they may 
change the baud rate, select the data format, and set the parity. The preceding 
example shows commands generated in BASIC; the command strings in the following 
sections are generated from die keyboard, 
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Commands useful in printer and communications modes 

The following commands are mosi useful in primer and communications modes. 

Baud rote, nB 

You can use ihe nB command to select die baud rate for die serial-port firmware. For 
example, to change the baud rale to 13 5, send Control-I 4B CR to the serial-port 
firmware (see Table 5-1), 



Table 5-1 








Baud- rot© selections 






n Baud rate 




n 


Baud raf» 


Default' 




8 


1200 


1 50 




9 


:*•.'■! 


2 75 




10 


2400 


3 110 




11 


3500 


4 13^.5 




12 


4800 


5 150 




13 


7200 


6 300 




14 


5600 


7 600 




15 


19,200 


* You set the default 


by 


usinf] 


ihe Control 


Panel. 









Data format, nD 

You can override the Control Panel sening that specifies the data format by using the 
nD command Table 5-2 shows how many data bits and slop bits correspond to each 
value of n. For example, Conlrol-I 2D makes the serial-port firmware transmit each 
character in the form of 1 start bit (always transmitted), 6 data bits, and 1 stop bit. 



Table 5-2 
Data-formal selections 


Data 
n bits 


Stop 
bits 


8 


1 


1 7 

2 6 


1 
1 


3 5 

4 8 


1 
2 


5 7 

6 6 


2 

2 


5 


2 
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mr 
Parity, nP 






You can use (he nP command to set the parley that you want to use for data 
transmission and reception. Four parity options are available. These are listed in 

Table 5-3. 






Table 5-3 

Parity selections 






n Parity value 




■ None (default value) 
I] Odd 
Iz None 
D 3 Even 




1 ♦ Note: The SCC 8530 does not support MARK and SPACE parity. 






Line length, nN 






The line length is set by sending Conixol-1 nN. The number n can be in the range of 1 
1 to 255 characters. For example, if you send Conirol-I 75N, the line length is .set to 75 
characters. fJVole Use the C command, discussed next, to enable line formatting.) If 
you sel n to 0, formatting is disabled. 






Enable line formatting, CE and CD 






: A forced carriage return is invoked after a lineful of characters by sending Conuol-I 

CE For example, Control-I 75N (see "Line Length'' above) and Control-I CE cause a 
j forced carriage return after 75 characters are typed on a line. 






Handshaking protocol, XE and XD 






Sending Control-I XE CR or Control-I XD CR to the serial-port firmware determines 
whether the firmware looks Tor any XOFF (Si 3) character coming from a device 
attached to the SCC. It responds by halting transmission of characters until the serial- 
port firmware receives an XON ($11) character from the device, signaling the SCC to 

i continue transmission. In printer mode, this function normally is disabled. 






XE = Dried XOFF, awaii XON. 
XD = Ignore XOFF. 






Operating commands 89 







Keyboard input, FE and FD 

The FD command is used to make Lhe serial-port firmware ignore keyboard input. For 
example, you can include Control-1 FD CR in a program, followed by a routine that 
retrieves data through the serial-port firmware, followed by Control-I FE CR to turn the 
keyboard back on. As a default, the serial-port firmware keyboard input is enabled. 

FE ■ Insert keystrokes into serial-port Firmware input stream 
FD = Disable keyboard input. 

Automatic line feed, LE and LD 

The automatic line-feed command causes the serial-port firmware to generate and 
transmit a line-feed character after each return character. For example, Control-I LE 
CR to print listings or double-spaced text. 

LE - Add line feeds after each carriage return output. 
LD - Do not add line feeds after carriage return output 

Reset the serial-port firmware, R 

The R command resets the serial-port firmware,, cancels all previous commands to the 
serial-port firmware and reinstalls the Control Panel default settings. Sending 
Control-I R CR to the serial -port firmware has the same effect as sending PR*0 and N-*0 
to a BASIC program and then resetting the serial-port firmware, This call also 
relinquishes any memory obtained from the Memory Manager for buffering purposes. 



C 
1 



•] 

[': 
1 



Suppress control characters, Z 

The Z command causes all further commands to be ignored This command is useful 
when the data you are transmitting (for mstance, graphics data) contains bit patterns 
I ha l the serial-port firmware could mistake for control characters. 

Sending Control-I Z CR to the serial-port firmware prevents the firmware from 
recognizing any further control characters, whether from the keyboard or contained 
in a stream of characters sent to the serial-port firmware. All tabbing and line 
formatting are disabled after a Control-I Z command 



Impo riant 

The only way to reinstate command recognition after the Z command Is either to 
Initialize the serial-port firmware or to use the SetModeSits call described later In 
this chapter. 



BO 
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Commands useful in communications mode 

[.The following commands are most useful in communications mode. 

Echo characters to the screen, EE and ED 

The EE and ED commands are used to display (echo) or not to display a character on 
the video screen during communication. For example, if you send Control-A ED GR, 
the serial-port firmware disables the forwarding of incoming characters to the screen. 
This command can be used to hide a password entered at a terminal or to avoid the 
double display of characters. 

EE - Echo input. 

ED - Don't echo input 

Mask line feed in, ME and MD 

If you send Control-A ME to the serial-port firmware, the firmware will ignore any 
incoming line-feed character that immediately follows a return character. 

Input buffering, BE and BD 

The BE and BD commands control input and output communication buffering. 

Terminal mode, T and Q 

The T command transfers you to terminal mode. In this mode, you can communicate 
with another computer or a computer time-sharing service. Terminal mode is entered 
through the BASIC interface. This means that you must initialize the firmware by 
typing IN#n and then sending Control-AT. 

* Note: IN*n sets the port input link, and PR#n sets the port output link. The 
lowercase n indicates the port number. 

To quit terminal mode, send Conlrol-AQ. 

Often, when communicating with another computer in terminal mode, you want to 
send a break character to signal the other computer that you wish to signal the end of 
the current segment of transmission. To send a break character, send Control-AS CR. 
This command causes the serial hardware to transmit a 233-millisecond break signal, 
recognized by most lime-sharing systems as a sign-off signal. 
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Table 5-4 summarizes terminal -mode command characters, 



Important 

If you enter terminal mode and can't see what you type echoed on the video 
screen, the modem link may not yet be established or you may need to use the 
Echo Enable command (Control-A EE), 



Table 5-4 

Terminaf-mods command characters 

Character Description 



S 
T 

Q 



Transmits 233-millisecond break (all zeros) 
Enters terminal mode 
Exits terminal mode 



Tab in BASIC, AE and AD 

If you send Control-I AE CR to the serial-port firmware, the BASIC horizontal position 
counter is left equal to the column count. Tabbing initially is disabled. It is up to the 
program to enable this feature if tabbing is desired, 

Al - Implement BASIC labs. 

AD = Do not implement BASIC tabs. 



Programming with serial-port firmware 

The serial-port firmware provides two interfaces: one for BASIC and one that adheres 
to the Pascal 1.1 firmware protocol. 

•I* Vote- To use the serial-port firmware, you must set the 65816 data bank register to 
$00, shift to emulation mode (e bit set to 1), and then issue your call. All entry 
points are in the SCnOO space in bank 500. (This applies to all calls to serial-port 
firmware.) 
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BASIC interface 






The following entry points accommodate the BASIC interface (n is the slot number, 

which can be 1 or 2); 

CnOO BASIC initialization (atso outputs character in the accumulator) 

jCn05 BASIC read character (character returned to accumulator; X, Y preserved) 

$CnQ7 BASIC write character (character passed through accumulator; X, Y preserved) 

Although the call to SCNOO coincidemally outputs the character in the accumulator, 
you should not use this side effect as the standard means of character output. Rather, 
you should use the JCN07 entry point for output of all but the first character (thai is, 
initialize the serial port only once). 

When you type IN#n or PR#n (set input or output link), BASIC makes a call lo 
$CnOO after it sets either the KSWL or CSWL link to $CnOO. When the serial-port 
firmware has control, it alters the links so that they point to the firmware Read and 
Write routines. 



Pascal prctacol far assembly language 

If you are a machine-language programmer, you should use the Pascal 1.1 protocol to 
communicate with the serial-port firmware. The Pascal 1.1 protocol interface is more 
flexible than die BASIC protocol. The Pascal 1.1 protocol uses a branch table in the 
SCnOG page to indicate where each of the service routines begins (see Table 5-5). 

For example, to reach the Read routine, read the value contained in location $CnOE 
{suppose it is Si 8) and then execute a JSR instruction to the address Cfor example. 
5Cnl8). Table 5-6 lists the I/O routine offsets and registers. 

♦ Note. The Pascal interface assumes that the application supplies a line feed after a 
carriage return, overriding the Control Panel setting. If the application does not 
supply line feeds, it should send the LE (line feed generation) call described in the 
section. "Command Strings' earlier in this chapter. 



labia 5-5 

Service routine descriptions and address offsets 



Jtoutin» noma 



Address 

OffjBt 



Description 






Initialization 

Read 
Write 
Status 
Control 



SCnOD 

SCnOF 
SCnlO 
SCnl2 



Reset port, restore Control Panel defaults 

Wait for and get next character 

Send character 

Inquire if character has been received 

Access extended interface commands 
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Table 5-6 

I/O routlrv© offsets and registers for Pascal 1.1 firmware protocol 



Address 
offset 


When used 


X register 




Y register 


A register 


SCnOD 


Initialization 
On entry 
On exit 


SCn 

Error code 




SnO 
Undefined 


Undefined 


SCnOE 


Read 
On entry 
On exit 


$Cn 
Error code 




SnO 

Undefined 


Character read 


SCnOF 


Write 
On entry 
On exit 


SCn 
Error code 




SnO 
Undefined 


Character to write 
Undefined 


SCnlO 


Status 
On entry 
On exit 


SCn 
Error code 




SnO 
Undefined 


Request (0 or ])♦ 
Undefined 


Extended 
Interlace! 

SCn 12 


Control 

On entry 
On exit 


Command lisi 
address (a. 15) 
Undefined 


Command list 
address CI 6.. 23) 
Undefined 


Command list 
address (CL7) 
Undefined 



" Request code means Are you ready to accept output? Request code 1 means Do you 

kSH$ mm «8^' On S&, InS ®$ IS tr£ 3&EU5 requeii is In ihe cany ft ai felfe 
Carry - means no; Cany - 1 means yes, 

t If the function call returns with the carry bit set, an error is returned Ln the accumulator. The 
Status call can return a "bad request code" ($40). Result codes returned by the extended 
interface are as follows: 



Err-i lype 

No error 

Bad call Error 

Bad parameter count 



Explanation 



Error code 
50000 



No problem detected. 

Illegal command used, lOOOl 

Parameter count not consistent with command requested. $0002 



B 



94 



Chapter 5: Serial-Port Firmware 



Error handling 

When the serial-port firmware receives a character from the hardware, it checks the 
error status register in the SCC. If the character has a framing or parity error (assuming 
that the parity option is not set to None), the character is deleted from the input 
stream and the appropriate bit-mode bit is set. You can use the GetModeBiis call to 
read these two bits Cone for framing errors and the other for parity errors) to 
determine whether at least one receive error has occurred. After you read these bits, 
jrou should dear them (using SetModeBits) so that future errors can be detected. Error 
checks should be performed periodically so that you will know whether received data is 
accurate. 






Buffering 

Input and output communications and background printing can be transparently 
buffered. Each port has two buffers: one for input and one for output. Default buffers 
ue 2048 characters each. !f you wish to use a buffer larger than this,, you must pass the 
address and length to the firmware by way of the extended-interface instruction 
SetlnBuffer or SetOutBuffer, You can allocate up to 64K bytes. 

♦ Note: In systems with little RAM remaining, you can reduce the size of the I/O 
buffers to 128 bytes. 

You can enable buffering by using the PR#n command from BASIC if the buffering 

option has been set in the Control Panel. If the buffering option has not been set, you 
can still enable buffering from die keyboard or by sending the BE command through 
the output flow. When buffering is enabled for output, characters sent to the firmware 
are placed in a FIFO (first in, first out) queue in the output buffer. These characters are 
sent out on an interrupt basis whenever the hardware is ready to send another 
character. 

The XON and XOFF characters are not queued; they are sent directly through the 
channel so that the data flow to the Apple IIGS may be stopped or restarted 
immediately Characters received in the buffering mode are placed in the input 
queue, and all read calls return characters from the queue. Any XON and XOFF 
characters received are not queued, so the output flow can be halted or resumed 
immediately upon reception. 

When the input queue becomes more than three-fourths full, the firmware attempts to 
disable the handshake. The firmware sends an XOFF character (if XON/XOFF 
handshaking is enabled), or the DTR line is disabled (if DSR/DTR handshaking is 
enabled). You can determine, through your application program, thai the handshake 
has been disabled by inspecting the input flow mode bit using the GetModeBits call in 
the extended interface. The firmware reenables the handshake as soon as the receive 
queue fills less than one-fourth of the input buffer. 
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You can determine ihe number of characters in the input queue or ihe amount of space 
left in Ihe output queue by using the InQStatus and OutQSiatus commands in the 
extended interface. Also, the InQStatus call returns the amount of time elapsed since 
the last character was queued. This allows a program to keep track of the input stream 
activity level even though it is not involved in the interrupt process. 

♦ Note: The InQStatus elapsed time counter function* correctly only if the heartbeat 
interrupt task has been started The heartbeat intern i pi task is a set of functions 
called by interrupt code thai run automatically at one-thirtieth of a second 
intervals. 



Interrupt notification 

When a Channel has buffering enabled, ihe firmware services all interrupts that occur 
on lhat channel. If an application wishes to service interrupts for a given channel 
itself, it should disable buffering using ihe BD command in the output flow. If the 
buffering mode is off, the serial-port firmware will not process any interrupts, Ihe 
system interrupt handler will transfer control to the user's interrupt vector as 503 FE in 
bank 500. (This is the ProDOS user's intemipt vector.) The user's interrupt service 
handler is then completely responsible for all .serial-port firmware interrupt service. 

If the application does no! want to disable buffering, but does wish io be notified when 
a certain type of serial interrupt occurs, it can instruct the firmware to pass control to 
an application-installed routine after the system has serviced the interrupt. The 
application tells the firmware when it wishes to be notified and establishes the address 
of die applications completion routine by using the Serimlnfo routine. (See 
Chapter 8, "Interna pt-Handler Firmware," for more information about interrupt 
routines.) This call guarantees that the completion routine will gel control when a 
specific type of interrupt occurs, but only after the serial-port firmware has processed 
and cleared Ihe interrupt, The application then uses the Ceilntlnfo routine to 
determine which interrupt condition occurred. 

A terminal emulator ofFers a typical example of when interrupt notification might be 
desirable Ihe emulator usually should perform input and output character buffering, 
handshaking, and other such operations The Terminal emulator can be designed to ' 
allow the firmware to handle all character-buffering details, The designer of the 
emulator can have the firmware signal the emulator program when the firmware 
receives a break character. To enable this special-condition notification, the emulator 
application sets the break interrupt enable function by using the Setlntlnib routine. 
Now whenever the firmware receives a break character, the firmware SCC interrupt 
handler records and clears the interrupt, finally passing control to the emulator's 
completion routine. This routine calls Getlntlnfo, and if the break bit is set, the 
completion routine knows that a break character has been received. 
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Note that all interrupt sources (except receive and transmit) cause an interrupt on a 
transition in a given signal. This means that a user's interrupt handler will get control 
passed to it on both positive and negative transitions in the signals of interest. For 
example, a break-character sequence causes two interrupts: one at the beginning of 
the sequence and one at the end. The user's interrupt handler should take this into 
account A routine can always determine the current slate of the bits of interest by 
using the GetPortStat routine. 

The interrupt completion routine executes as part of the firmware interrupt handler 
ind must run in that environment, In addition, the following environment variables 
must be preserved by your routine: 

I - $00, e-0, m-1, x-1 

Kegtsters A, X, and Y need not be preserved. 



Background printing 

Apple IIGs allows you to print while running an application program. Printing while 
mother program is running is called background printing. Background printing is 
mother example of output buffering, as described in the section on buffering: In 
background printing, you send a block of characters over a serial channel on an 
interrupt basis. The major difference is that the firmware is handed a large number of 
characters to transmit all at once rather than getting them one at a time. 

To print in the background, perform the following steps; 

1. Issue an Init call through the Pascal interface. This ensures that the firmware and 
hardware are active. The hardware characteristics (baud rate, daia Format, and so 
on) will be as specified in the Control Panel. 

2. Disable buffering using the BD serial command in case the Control Panel was sei t< i 
enable buffering. 

3. If you want to change the port characteristics, specify them using either the 
SetModeBits call or the Send command in the output flow. 

4. Set the output buffer using SetOutBuffer. To use the default buffer, make a call to 
GctOutBufTer to ascertain its location. 

5. Load the data into the buffer. 

i, Start the printing process with SendQueue, passing the length of the buffer data and 
the address of the Recharge routine. 
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Recharge routine 

Once you start background printing with a SendQueue call, the firmware sends the 
characters periodically, in the background, until the buffer is exhausted- When the last 
character is removed from the buffer, the firmware executes a JSL to the Recharge 
routine, whose address was passed when the call to the SendQueue routine was made. 
This application-supplied routine reloads the buffer with die next get of data to be sent, 
a task that could involve some disk activity if the application is performing background 
printing from the disk. Finally, the routine loads die number of bytes in the new block 
of data to be sent to the X and Y registers (these will both be zero in case the 
background printing is complete) and executes an RTL, Requirements for the Recharge 
routine arc as follows: 



On entry 

System speed ■ fast 

DBR = $00 

Native mode (that is, m - 0, x - 0, e - 0) 



On axil 

System speed - fast 

DBR - $00 

Native mode, 8-bit m and x (e e 0) 

X register = data size Oow) 

Y register = data size (high) 

Note that the Recharge routine is called at interrupt time. Therefore, you should 
regard it as an interrupt handler, in the sense that anything it changes must be 
restored. Also note that interrupts are disabled during die time the Recharge routine is 
running. If too much time is spent in this routine, performance degradation of 
intcrrupt-critical processes will occur. An interrupl-cridcal process is one such as 
AppleTalk that has stringent interrupt- response requirements, 

* Note: The firmware reserves die last byte in the data buffer for empty buffer 
detection. Make sure that the buffer's size is 1 byle larger than the amount of data 
you place in it. For example, if GeiOulRuffer reveals an output buffer of 2048 bytes, 
only data lengths less than 2048 should be passed with the background- printing call 
or Recharge routine. 
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Extended interface 



The Apple IIGS system has extended call Features not present in the SSC, These calls 
are made through the extended interface and are divided into three groups: hardware 
control, mode control, and buffer-management features, A list of the extended 
Interface calls follows this section, 

You can make a call through the extended interface using the following method; 

1. Determine the dispatch address by adding the value $CN0O to the value located at 
5CM2. The byte at SCN12 is called the optional control routine offset of the Pascal 
1.1 protocol. 

2. Perform an emulation-mode JSR (DBR ■ $00) to this dispatch address, with the 
address of the command list (CMDLI5T) in the appropriate registers as follows: 

Begin er Register value 

Address of CM DUST (low) 
X Address of CMDLIST (medium) 

Y Address of CMDLIST (high) 

Hay command list starts with a 1-byte parameter count (not a byte count), a 
command code, and space for a result code. The possible result codes returned are 
listed in the section "Error Handling" earlier in this chapter. 

j» Note: If you want to ensure that your application will work with future systems, limit 
the use of hardware control calls, particularly the Gel SCC and Set SCC calls. If 

[ future systems use hardware other than the current serial chip (SCC 8530), your 
hardware control calk will most likely have to be changed. 

In the extended serial interface descriptions that Follow, a DFB is an assembler 
directive that produces a single byte, a DW is an assembler directive that produces a 
double byte (l6-bits: low byte, high byte), and a DL is an assembler directive that 
produces a double word Q2 bits, that is, 4 bytes). 



Important 

Different instructions require that a different number of bytes be reserved for the 
return parameters. Be sure that the CMDLIST buffer area to Which you point Is 
targe enough to hold all of the bytes of the return parameters for that command. 
'your buffer area Is not large enough, the system may fall, 
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Mode control calls 



GelModeBits 

Returns the current mode bit sellings. 



CM DUST 



DFB 
DFB 

DW 
DL 



$03 
SOO 
S00 
$00 



Parameter count 
Command code 
Result code (output) 
ModeBitlmage (output) 



This call allows the application lo determine the status of various firmware operating 
modes. Four bytes (32 bits) of mode information are returned To change any of these 
bits, use this call to get the current settings, then alter the bits of interest, and then use 
the SetModeBits call to make the actual modification. (To avoid race conditions in 
this process, be sure 10 disable interrupts during ihe reading, altering, and writing of 
the bits.) The meaning of each bit is described below. 



SeiModeBits 






Sets the mode bits. 






CMDLIST DFB 


$03 


-.Parameter count 


DFB 


$01 


.Command code 


DW 


$00 


;RcsuIt code (output) 


DL 


ModeBitlmage 


i(input) 



Use this call to alter any of the mode bits whose function is described above. First read 
in the bits using GetModeBits. then alter the bits of interest, and then write the bits by 
using this call. (Be sure to disable interrupts, as discussed in the GetModeBits 
description.) The bits marked Preserve should not be changed; they are informational 
only. Altering these bits will confuse the firmware. 

ModeBitlmage is 4 bytes, where bit is the least significant bit of the lowest addressed 
byte and bit 31 is the most significant bit of the highest addressed byte. 



131. -24] 


(Preserve) 


[231 


1 = Ignore commands in the output flow 


122] 


1 ■ Framing error has occurred 


121] 


(Preserve) 


[20] 


1 - Parity error has occurred 


119.. UH 


(Preserve) 


1 1 y . . i o i 




[15] 


(Preserve) 


[14] 


(Preserve) 1 - I/O buffering enabled 


H3I 


1 = DCD handshaking enabled 


[12] 


(Preserve) 


mi 


1 = Generate CR at end of line 



n 

[S 

[g 

[7 
[€ 

[5 
[4 

[2 
[2 

fl 

I' 



B 

G 

k 
C 



a. 



G 

R 

C 
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[10] 



17] 
\6] 
151 
14] 
131 
12] 
111 



(Preserve) 1 ■ Input flow halted 

(Preserve) 1 = Output flow halted 

(Preserve) 1 = Background printing in progress 

1 = Echo input to the video screen 

] - Generate LF after CR 

1 = XON/XOFF handshaking enabled 

1 = Accept keyboard input 

- Delete LF after CR 

1 - DTR/DSR handshaking enabled 
CPreserve) 1 = awaiting XON character 

(Preserve) 1 = communications mode, ■ printer mode 





Buffer-management calls 



GetlnBuffer 

Returns the address and length of the input butter. 



CM D LIST 



DFB 
DFB 

DW 
DL 

DW 



510 
$00 
500 
S00 



Parameter count 
Command code 
Result code (output) 
Buffer address (output) 
Buffer length (output) 



This catl and the one that follows (GetOutBuffer) are used to determine the addresses 
and lengths of the current input and output buffers. If background printing is to be 
invoked and the application wants to use the default buffer, its address can be retrieved 
by these calls 



GetOutBuffer 

Returns the address and length of the output buffer. 



CMDLIST 


DFB 


S04 




DFB 


511 




DW 


S00 




DL 


soo 




DW 


$00 



Parameter count 
Command code 

Result code (output) 
Buffer address (output) 
Buffer length (output) 
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Setln Buffer 








Specifies ihe buffer 


to contain ihe input 


queue. 


CMDLIST DFB 


$04 


iParameter count 


DFB 


$12 




Command code 


DW 


$00 




Ri-si:ll rode (output) 


DL 


Buffer address 




(input) 


DW 


Buffer length 




(input) 



This call and the one following (SetOu [Buffer) allow the application to change ihe 
location and length of the input or output buffers. A queue buffer can cross bank 
boundaries but must be fixed in memory while buffering is active. 



SetOut Buffer 

Specifies the buffer to contain the output queue. 



CMDLIST 


DFB 


$04 


Parameter count 




DFB 


$13 


Command code 




DW 


$00 


Result code (output) 




DL 


Buffer address 


i input) 




DW 


Buffer length 


(input) 



Flush In Queue 

Discards all characters in Ihe input queue. 

CMDLIST DFB 
DFB 
DW 



S02 
$14 

too 



Parameter count 
Command code 

Result code (output) 



This call and the one following (MushOutQueue) allow the application to flush 
unwanted data ff5fn the input and output queues. 



FlushOutQueue 

cards all the characters in the output qyeue. 



CMDLIST 



DFB 
DFB 



$02 
$15 
JOO 



Parameter count 
Command code 
Result code (output) 
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InQStatus 

Returns information aboul ihe input queue. 

CMDLIST 



DFB 


$04 


DFB 


$16 


DW 


$00 


DW 


$00 



DW 



$00 



Parameter Count 

Command Code 

Result Code (output) 

Number of characters in receive queue 

(ouipuO 
;Time since last receive character queued 

CoutpuC 



Tm call and the one fallowing (OujtQStatus) call return informaiion about the input 
and output queues. The InQStatus call additionally returns the number of hean 
ticks (1 tick » 1/30 second) between the time the last character was queued and the time 
of the call. Note that for this number to be valid, the application must have turned on 
the heartbeat system by making a tool call. 



OutQStafus 

Returns information about the output queue. 



CMDLIST 


DFB 


$04 






$17 




DW 


$00 




DW 


$00 



DW 



$00 



Parameter count 
Command code 
Result code (output) 
Number of characters until transmit 
queue overflow (output) 
;Reserved (output) 



SendQueue 






Launches background printing. 




CMDLIST DFB 


504 


.Parameter count 


DF13 


$18 


.Command code 


DW 


$00 


•.Result code (output) 


DW 


Data length 




DL 


Recharge address 





This call begins the background-printing process. The application must First set the 
output buffer address Cor use the default buffer) to load the data to be output into the 
buffer starting at-the buffer base address. The data then is placed into the buffer. The 
call to SendQueue then must be made specifying the length of the data in the buffer 
and the 4-byte address of a subroutine (the Recharge routine), which will be called by 
the interrupt firmware when all characters have been sent. (See the section earlier in 
this chapter for further information aboul Recharge.) 
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Hardware control calls 

Refer to the section "Compatibility" at the beginning of this chapter. 



GetPortStot 

Returns the pon hardware status. 



CMDLI5T 



DFB 
DFB 
DW 

DW 
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$06 
JOC 

$00 



■Parameter count 
.Command code 
.Result code (output) 
;Port status info (output) 



[15. .81 




[71 


Break/Abort 


[6] 


Tx Underrun 


E51 


DSR 


h. 




I3i 


DCD 


\2. 


Tx Buff Empty 


[11 




!■:: 


Rx Char Avail 



This call is used to get the current status of the serial channel at the hardware level. 
There are 16 bits of result. The meaning of these bits is as follows: 

(Reserved) 

'-■•_-. l" } when :t break sequence i.s delected 

Sel to 1 when a transmit underrun occurs 

State of the input handshake line 

(Reserved) 

Slate of the general-purpose input line 

Set to 1 when ready to transmit next character 

(Reserved) 

Set 10 1 when a character is available to be read 



GetSCC 

Returns the value of the specified SCC register. 

Parameter count 

Command code 

.Result code (output) 

iSCC register number (input) 

.Value of SCC register (output) 

GeiSCC returns the value in a specified SCC register. The GetSCC and SetSCC calls 
allow direct access to the serial hardware. (See the SCC 8530 technical manual for a 
description of the registers in the serial controller chip.) The serial-port firmware 
does not need to be initialized for these calls to work; in fact, these calls should be used 
only if the application is handling all serial tasks itself and not using the firmware at all. 



CM D LIST 


DFB 


$04 




DFB 


$08 




DW 


-.::■■: 




DFB 


Register 




DFB 


$00 



S€ 

w 
en 



IT 
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Re 

a 



U." 
th 

by 

St 
Se 
CI 



U« 

G 

Re 
CI 



Tt 

AS 
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s©rscc 




Writes a value into the SCC 


CMDLIST DFB 


$04 


DFB 


$09 


DW 


$00 


DFB 


Register 


DFB 


Value 



.Parameter count 
;Conimand code 
; Result code (output) 
;SCC register to write (input) 

.Value Lu write lo Register (input) 
is call allows the writing of a register in the M I ', 



GefDTR 

I Returns the value of the output hands hake line 

lOtDUST DFB J03 .Parameter count 

-Command code 
.Result cade (output) 
;Bil 7 is the state of DTR (output) 

[Use this call to find out the current selling of the outpul handshake line The slate of 
this line is returned in the most significant bit of the returned byte The line may be set 
by the SetDTR call. 



DFB 


$03 


DFB 


SOA 


DW 


$00 


DW 


$00 



SetDTR 

Sets the value of the output handshake- line 

;P<tramelci COUTH 

^Command code 

iHesuli code (output) 

,Bu 7 is the state of DTR (input) 

Use this call to set the current mode of the output handshake line 



CMDLIST 


DFB 


$03 




DFB 


SOB 




DW 


$00 




DW 


DTR slate 



Getlntlnfo 

Returns the type of interrupt (for use in the imc-uupt completion raurj 



CMDLIST 


DFB 


$03 




Parameter count 




DFB 


SOC 




Command code 




DW 


$00 




Result code (output) 




DW 


$00 




(output) 




DL 


Completion 


address 


(outpul) 



This call allows the application to determine which type of Interrupt caused the 

alion's completion routine to be called The meanings uf the bits are the same 
as for ScrJntlnfo- 
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Set In f Info 






Sets up informational interrupt handling. 




CMDL1ST DFI5 


S03 


Parameter count 


DFR 


SOD 


Command code 


D¥ 


SOO 


Result code (output) 


DW 


Interrupt setting 


(output) 


DL 


Completion address 


(input) 



Hi-* cal illows the application to specify the r^pes of Nemjpts thai wffl be passed to 
the application's interrupt routine, The firmware should be enabled and buffering 
turned on when this call is made. The types of interrupts and the bits used to enable 
them are as shown in Table 5-7. 

The extended serial-port commands are summarized in Figures 5-4 and 5-5. 

Table 5-7 

Interrupt setting enable bits 



[15..8! 


(Reserved) 


171 


Break/Abort 


161 


Tx tlnderrun 


151 


CTS 


Nl 





131 


DCD 


121 


Tx 


tl] 
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Rx 



Set these to zero 

Break sequence deled 

Transmit underrun detect 

Transition on input handshake line 

(Reserved) 

Transition on general-purpose line 

Transmit register empty 

(Reserved) 

Character available 
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i 
1 

4 

2 

1 

1 

4 


GeflnBuffer 


2 

4 
2 


GetOutBuffer 


l 

i 
2 

4 

? 


SellnRuffer 


Poromerer count = sofl 


Parameter count = 504 


Parameter count = $04 


Command code = 510 


Command code = $11 


Command code - S 12 


Result code 


Rosull code 


Result code 


Buffer base address 


Buffer base address 


Buffer base address 


Surfer length 


Buffer length 


Buffer lor 


Return locoiion and length 
of fhe receive queue buffer 




Return location and lenglh 
of the transmit queue buffer 




Set location and length 
ol fhe receive queue bufei 


SetOutBuffer 


1 
1 

2 
c 
2 

1 

2 
2 

2 


Flu thin Queue 


1 


FlushOufQueue 


Parameter count = $04 


Parem. S02 


Parameter count = $02 


Comrnandcodo = 


Command code s 


Command code * 5 15 


BenJt code 


ftasult code 


Result code 


Buffer base address 


Tnrow away all characters 
In the receive queue 




Throw away all characters 
In the transmit queue 


Buffer length 




Set location and length 

of the transmit queue Duffer 








InQSIatus 


OurQStatus 


2 
2 
2 


SendOueue 


Parameter counl = SQ4 


Parameter count ■ 304 


Parameter count = $04 


Command code ■ S 16 


Command code == S 1 7 


Command code - $ 18 


Result code 


Result code 


Result code 


Number of characters 
in receive queue 


Number of character spaces 

left in transmit queue 


Data ler 


Number ot ticks since 

losi character arrived 


Reserved 


Completion address 


?etum receive queue Inform atlor 

Figure 5-4 

Summary of extended serial-p 


ortt 


eturn transmit queue In formatter 
juffer commands 


T 


Begin background output 
Extended Interface 













GetModeBIti 




ei count = 


S03 


Command code ■ 


SCO 




Result code 




BIT settings 



Return firmware mod© btfs 



SefModoBlts 


■ S03 




Command code = SOI 


Result code 


settings 





GetPortStat 
t rameter c< 



■ter co 



Command code s S06 
Result code 



Port hardware status 



: 



Set firmware mode bits 



Return the port sfalus 



GetSCC 



Porn 



Command code = $08 



Result code 



SCC register numDer 



Register value read 



SetSCC 



Pa'ameisr cc 



\icode = $09 

- 



Result code 



SCC regis'' 



GetDIR 



'Jesuit coce 



DTI? state (bit 7) 



meter count *= I 

I 



Register voIub to v. 



1 Return state of output handshake 



Return on SCC 6530 register value Write an SCC B&30 register value [npuf pcHamefo , 



SelDTR 




id code -SOB 


Result code 


**m»~mmi> 



Set state of output handshake 



Getlnllnfo 



Parameter cc. 



Command code = 50C 



Result code 



ii 1 5-D"i"g 



Completion routine address 




Return informational interrupt byte Set mfofmaftonal Interrupt parameters 



Figure 5-5 

Summary of extended serial -port mode and hardware control commands 
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This chapter describes the Apple 1IGS Disk II support. Several different types of disk 
drives can be attached to the Apple IIGS si mr of which contain built-in intelligence 
This chapter describes the methods by which the Disk II product can be connected to 
the Apple IIGS. The Apple IIGS disk-support system, with its built-in Integrated Wo?. 
Machine (IWM) chip, accommodates Disk II (DuoDisk and UniDisk) 5.25- inch drives, 
35-inch drives with built-in intelligence (UniDisk 3.5), and Apple 3.5 drives. 

The IWM divides the Apple IIGS disk pott Con the back of the computer) into I/O ports 
5 and 6. The ports are equivalent to internal versions of device drivers installed in 
expansion slots 5 and 6, respectively. The Control Panel setting for slot 5 or 6 
determines whether the I/O port or a card physically present in that slot is active. 

Port 6 provides die standard Disk II support Djsk II boot routines are ml into ROM. 
Disk II routines in DOS, ProDOS, and Pascal operate the same as they do in Apple 11 
computers prior in ihe Apple IIGS. Direct access lo Disk II devices (reading and 
writing tracks and sectors, seeking to specified tracks, and so on) is provided by 
whichever operating system you boot- Separate firmware support is provided only for 
booting from Disk II devices 

Port 5 is called SmartPort. It consists of an expanded version of the SmartPort 
firmware used in the 32K Apple II ROM. SmartPort is capable of supporting a 
combination of character and block devices up to a total of 127 devices. It controls the 
UniDisk 3.5 and Apple 35 drives as well as the ROM disk and the RAM disk. The 
SmartPort firmware is discussed in detail in Chapter 7, "SmartPort Firmware " 

You can attach up to two Disk II drives, two Apple 3-5 drives, and two or more 
UniDisk 3-5 drives to the Apple IIGS disk port, depending on IWM output 
specifications. A maximum of six devices can be connected at any one lime. The disks 
must be attached in the order shown in Figure 6 1 (Apple 3 5 drives first, followed by 
UniDisk 3.5 drives, followed by Disk II drives). 




Apple 3.5 
drive 



Apple 3 5 
drive 



UniDisk 3 5 
drive 



I/O port 5 



(UmDiW 5.25 and 
DuoDlsk drives) 

I/O port 6 



Figure 6-1 

Order of disk drives on Apple IIGS disk ports 
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Interface routines for ports 5 and 6 access ihe TWM using slot 6 sofi switches. The 
firmware arbitrates between slot use of the same soft switches. If a peripheral card is 
plugged into slot 6, the firmware in port 5 can still access the disks connected Co port 6 
by temporarily disabling the external peripheral card, performing disk access, and 
then neenabling the external peripheral card. 

The port 6 disk interface firmware resides in the 5C6O0 address space. It supports up to 
two drives, addressed as though they are connected to slot 6, as physical drives 1 and 
2, Both drives use single-sided, 143K-capacity, 35-track, 16-sector format Table 6-1 
summarizes the Disk II I/O port characteristics. 

Table 6-1 

Disk II f/O port characteristics 



Drive number 

Commands 

Initial characteristics 

Hardware location 

Monitor firmware routines 
I/O firmware entry points 

Use of screen holes 



Port 6, drive 1 
Port 6, drive 2 

IN#6 or PR#6 from BA5IC or Call -151 (to get 
to Monitor from BASIC) and 6 Control-P 

All resets with valid reset vector, except Control-Reset, 
pass control to slot 6 drive 1 if Lhis drive is set (through 
Control Panel) as boot device or if scan is selected and 
no boot volume is found in higher-priority slot 

internal, SCOE0-SC0EF, reserved for Disk II and 
SmariPort use 

None 

SC600 (port 6 boot address) 

SC65E (read first track, first sector and begin execution 

of code found there) 

Port 6 main- and auxiliary-mem ory screen holes 
reserved 
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Startup 

Tile Apple IIGS can be started by using either a cold start or a warm start, A cold start. 
clears the machine's memory and tries to load an operating system from disk. A warm 
start stops the program currently running and leaves the machine in Applesoft BASIC 
with memory and programs intact 

A cold start can be initiated by any of the following: 

- turning the machine on 

z pressing cJ-Control-Reset 

Q issuing a reboot command from the Monitor, from BASIC, or from a program 

□ pressing Control-Reset if a valid reset vector does not exist 

If you have set the startup device Cfrom the Control PaneD to slot 6 or if you have 
selected scan and no boot volume is found in a higher-priority slot, the cold-start 
routine first sets a number of soft switches (see Appendix E, "Soft Switches") and then 
passes control to the program entry point at $C600. This code turns on the Disk II 
unit 1 device motor and then recalibrates the head to track and reads sector from 
that track. The sector contents are loaded into memory starting at address S0800; then 
program control passes to $0801. The program loaded depends on the operating 
system or application program on the disk. 

To restart the system from BASIC, issue a PR*6 command, from the Monitor 
command mode, issue 6 Control-P; and from a machine-language program, use JMP 

§6698: 

A warm start begins when you press Control -Reset if a valid reset vector exists 

Normally, a warm start leaves you in BASIC with memory unchanged. If a program has 
changed the reset vector, the system will not perform a warm start. Usually, a program 
cither performs a cold start or beeps and does nothing, leaving you in Lhe currently 
executing program. 
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The SmartPort firmware is associated with I/O port 5 (internal slot 5). It consists of 
assembly-language routines that support a series of block or character devices 
connected to the Apple IIGS external disk port. The SmartPort firmware converts calls 
to an appropriate format for transmittal over the disk port lo control intelligent 
devices, that is, devices that can interpret command streams, such as the UniDisk 3-5 
drive. The SmartPort abo provides an interface to several unintelligent devices, that 
is, devices that require specific hardware control and employ no built-in intelligence, 
through the use of device-specific drivers that are accessed through the SmartPort 
extended interface calls. Unintelligent devices supported on the Apple IIGS through 
the SmartPort include the Apple 35 drive, RAM disk, and ROM disk. 

To use the SmartPort interface, a program issues calls similar to ProDOS 8 machine- 
language interface calls. Each call consists of a JSR to the SmartPort entry point, 
followed by a SmartPort command byte, followed by a pointer to a table containing 
the parameters necessary for the call. The calls lo SmartPort take two possible forms. 
The standard version of a call allows your program to move data to and from bank $00 
of the memory. You use the extended version of the call to move data to and from 
Other banks of memory. 



Locating SmartPort 

You can determine whether the SmartPort interface is installed in a system by 
examining the ProDOS block-device signature bytes shown hcie 

SCnOl - $20 

SCn03 - $00 
SCn05 - $03 

You must also verify the existence of the SmartPort signature byte; 
5Cn07 - $oo 

In the preceding addresses, n is the slot number for which the signature bytes are being 
examined. All peripheral cards or ports with these signature-byte values support both 
ProDOS block-device calls and SmartPort calls. You can examine the SmartPort ID 
type byte to obtain more information about any special support that may be built into 
the SmartPort driver. The SmartPort ID type byte located at SCnFB has been encoded 
to indicate the types of devices that can be supported by the SmartPort driver. This 
byte pertains to the interface only. For example, the Apple IIGS SmartPort interface in 
internal slot 5 may support a RAM disk, but it is not a RAM card, so bit is cleared. 
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F^ure 7-1 illustrates the contents of this ID type byte. Note that a driver thai supports 
extended SmartPort calls must also support standard SmartPort calls. Bit 1, SCSI, 
indicates support for the Small Computer System Interface (SCSI). 

SC 

RAM card 

SCSI 

Reserved 

Extended 



SmartPort ID type 



SCnFB 



Flgur» 7-1 

SmartPort ID type byte 



Locating the dispatch address 

Once you liavc UcicruilncU thai a StuaiU'uu ULLUjfaLu existi in a slot or port, you need 

to determine the entry point, or dispatch address. For the SmartPort, This address is 
f determined by the value found at SCnFF, where n is the slot number. By adding the 
value ai $CnFF to the address $CnOO, you can calculate the standard ProDOS block- 
<fevice driver entry point. More information about this entry point is available in the 
ProDOS Technical Reference. The SmartPort entry point is located 3 bytes after the 
ProDOS entry point. Therefore, the SmartPort entry point is SCnOO plus 3 plus the 
value found at SCnFF. 

For example, if the signature bytes For die SmartPort interface are in slot 5 and 3C5FF 
contains a hexadecimal value of SOA, the ProDOS entry point is 5C50A, and the 
SmartPort entry point is SC50A plus 3, or SC50D. 



Locating the dispatch address 
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SmartPort call parameters 



SmartPorl calls include several parameters. Not all parameters appear in every 
SmartPort call The parameter types thai may be required when making a SmartPort 
call are as follows 



Command name 
Command number 



Parameter list pointer 
Parameter count 

Unit number 

Buffer address 

Block number 

Byte count 
Address pointer 



Name used to identify the SmartPort call 

Byte value that you position contiguous in memory with the 
JSR lo the SmartPort. entry point; hexadecimal number that 
specifies the type of SmartPort call (bit 6 is cleared to for 
standard calls and set to 1 for extended calls) 

Pointer that you position contiguous in memory with the 
command number that points to the parameter list 

The first item in the parameter list; hexadecimal byle value 
that specifies the number of parameters in the parameter 
list 

Hexadecimal byte value that specifies the unit number of 
the device to or from which the SmartPort call is to direct 
I/O 

Pointer to memory that will be used in the I/O transaction 
(for standard SmartPort calls, this is a word-wide pointer 
referencing memory in bank zero; for extended calls, the 
pointer is a longword referencing memory in any bank) 

Number specifying the block address used in an I/O 
transacu'on with a block device (for standard SmartPort 
calls, this parameter is 24 bits wide; for extended calls, this 
parameter is 32 bits wide) 

Specifies the number of bytes to be transferred between 
memory and the device (this parameter is 16 bits wide) 

Specifies an address within the device 
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SmartPort assignment of unit numbers 

The unit number is included in every parameter list. The unii number specifies which 
device connected to the slot 5 hardware responds to the commands you issue. Calls 
that allow you to reference the SmartPort itself use a unit number of zero. Only Status, 
Init, and Control calls may be made to unit zero. The Apple IICS assigns unit numbers 
to devices in ascending order starting with unit number $01. Devices are assigned unit 
numbers starting with the RAM disk, ROM disk, and Apple 3.5 drive, and finally 
[proceeding to intelligent devices such a.s the I 'niDisk 3.5. 



Allocation of device unit numbers 

The Apple IIgs implementation of the SmartPort interacts with the Control Panel 
selection of boot devices. For any given port, a boot can occur only from the first 
device logically connected to that port. Booting from Disk II devices is handled by the 
slot 6 firmware. SmartPort support is provided lo allow booting from any of three 
\ types of devices: 

t RAM disk 

□ ROM disk 

p Disk drive (Apple 3.5 drive or UniDisk 3,5) 

Depending on the devices that arc connected to the slot 5 hardware, the selected boot 
device may not be the first logical device in the chain. To boot from the selected 
device, using the Control Panel settings, the SmartPort firmware logically moves the 
selected device to the first unit in the device chain. All devices that were previously 
ahead of the selected boot device must then be moved logically so that they are now 
located behind the selected boot device. 

The initialization call handles assignments of unit numbers in a two-stage process. In 
the first stage, unit numbers arc assigned as described above, in the section 
"SmartPort Assignment of Unit Numbers." In the second stage, the units are 
remapped so that the selected boot device is always the first logical device in the 
chain. If Scan is selected as the boot option in the Conirol Panel, the SmartPort places 
the iirst physic.il dish drive .i--. the Srsi logical device in ('no device chain 

Device remapping is necessary for certain device configurations under ProDOS. 
Current implementations of ProDOS (both ProDOS 8 and ProDOS 16) support only 
two devices per port or slot. If more than two devices are connected to the device 
chain, devices beyond the second cannot be accessed ProDOS 8 and ProDOS 16 gee 
iround this restriction by logically mapping devices beyond the second device SO thai 
ihey appear to be connected to slot 2 Using this method, ProDOS 8 and ProDOS 16 
can support up to four devices on the chain. 

* Note: Future versions of ProDOS 16 will support more than two devices per port or 
slot so that no remapping of units to slot 2 will be necessary. 

SmartPort assignment of unit numbers 
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Figures 7-2 through 7-6 show device remapping derived from the selected boot device 
versus the device configuration. Only a few of the possible remapping variations are 
shown. 
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Device mopping: configuration 1, derivation 1 



ram disk 
Stage 1 . unit 



S^afPorl 



if RAM disfc is boot 
aiyvco. tier 




RAM disk 
Stage 2, unit l 


SmarrPort 




— — 







Apple 3.5 drive 
Stage 1, unit 2 



Apple 3.5 drive 
Stage 1 , unit 3 



* ► 



1' 

Apple 3.5 drive 
Stage 2, untt 2 




Apple 3 5 drive 
Stage 2, unit 3 



Figure 7-3 

Device mopping: configuration 1, derivation 2 
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Device mapping: configuration 2, derivation 2 
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Issuing a call to SmartPort 

SmartPort calls fall into two categories: standard calls and extended calls, Standard 
SmartPort calls are designed for interfacing Apple II peripherals. Extended SmartPort 
calls are designed for peripheral devices that can take advantage of the 65816 
processor's ability to transfer data between any memory bank and the peripheral 
device and may require larger block addressing than is possible with the standard 
SmartPort calls. 

For standard SmartPort calls, the pointer following die SmartPort command byte is a 
word-wide pointer to a parameter list in bank zero. For extended SmartPort calls, the 
pointer is a longword pointer to a parameter list in any memory bank. 

There are several constraints on the use of the SmartPort: 

□ 'l*he stack use is 30-35 bytes. Programs should allow 35 bytes of stack space for each 
call. 

D The SmartPort cannol generally be used to put anything into absolute zero page 
locations. Absolute zero page is defined as the direct page when the direct register is 
set to S00OO. 

□ The SmartPort can be called only from Apple 11 emulation mode. This means that 
the emulation flag in the 65C816 processor status byte must be set to 1 , and the 
direct-page register and data bank register mu.st both be set to zero. Native-mode 
programs wishing to call the SmartPort must switch to emulation mode prior to 
making a SmartPort call, Such programs may cause corruption of the contents of 
the stack pointer. Refer to Chapter 2, "Notes for Programmers," for more 
information about switching processor modes. 

This is an example of a standard SmartPort call: 

;Call SmartPort command dispatcher 

;Thls specifies the command type 

;Word pointer to the parameter ]iat in bank Sod 

; carry Is set on an error 



5P CALL J5R 


DISPATCH 


DFB 


CMDNOM 


DM 


CMDLIST 


BC5 


ERROR 


This is an example of a 


extended Sn 


5P EXT CALL J5R 


DISPATCH 


DFB 


CMDNUM+S40 


m 


CMDLIST 


OH 


* CMDLIST 


BCS 


ERROR 



;Call SmartPort command dispatcher 
,'This specifies the extended command type 
; Low-word pointer to the parameter list 
; High-Word pointer to the parameter 
; Carry is set nn an error 

On completion af a call, execution returns to the RTS add/ess plus 3 for a standard call 

and to the RTS address plus 5 for an extended call Cthe BCS statement in the 
examples). If the call was successful, the C flag is cleared and the A register is set to 0; if 
it was unsuccessful, the C flag is set and the A register contains the error code. If data is 
transferred from the device to the CPU. the X register contains the low byte count and 
the Y register contains the high byte count. 
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The complete register Status upon completion is summarized In Table 7-1. 

Table 7-1 

Register status on return from SmartPort 



65*16 status byte 



N V I B D 



Z C Ace X Y PC 



SP 



Successful XX1X0UXO0 nn JSR+3 U 

standard call 

Successful X X 1 X U X Q nn JSR+S II 

extended call 

Unsuccessful X X 1 X U X 1 Error X X JSR+3 U 

standard call 

Unsuccessful X X 1 X U X 1 Error X X JSR+5 LI 
extended call 

* Mole. X undefined, U - unchanged, n - undefined for transfers to the device or number 
of bytes transferred when the transfer was from the device to the host. 



Generic SmartPort calls 

Generic SmartPort calls are explained in detail in the following sections. 






Status 

The Status call returns status information about a particular device or about the 
SmartPort itself Only Status calls that return general information are listed here. 
£>GVice-spedfic Status calls can also be implemented by a device for diagnostic or 
other information. Device-specific calls must be implemented with a status code of 
$0'i or greater. On return from a Status call, the X and Y registers contain a count of 
the number of bytes transferred to the host. X contains the low byte of the count, and 
Y contains the high byte of the counL 



Standard coll 

CMDNUM $00 

CMDLIST Parameter count 

I Init number 

Status list pointer flow byte) 

Status list pointer (high byte) 

Status code 



Extended call 

S40 

Parameter count 

l.lnii number 

Status list pointer (low byte, low word) 

Status list pointer (high byte, low word) 

Status list pointer flow byte* high word) 

Status list pointer (high byte, high word) 

Status code 

Generic SmartPort calls 
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Required parameters 

Parameter count Byte value = $03 

Unit number 1 byic value in the range $00, S II Da $7S 

Each device has a unique number assigned to il at initialization time. The numbers are 
assigned according to the device's position in the chain. A Status call with a unit 
number of $00 specifies a call for the overall SmartPort status. 



Sfandcrd cull 



Extended coll 



Status list pointer Word pointer (bank 500) Longword pointer 

This is a pointer to the buffer to which the status list is to be relumed. For standard 
calls, this is a word-wide pointer defaulting to bank SO0. For extended calls, this is a 
longword pointer. Note that the length of the buffer varies, depending on the status 
request being made. 



Status code 



1-byte value in the range 500 to SFF 



This is the number of the status request being made, All devices respond to the 

following requests: 



Status 
cod© 

SO0 
$01 
$02 

>U3 



Status returned 

Return device status 

Return device control block 

Return newline status (character devices only) 

Rc-lum device; information btOCk CDIB) 



Although devices must respond to the preceding status requests, a device may not be 
able to support the request. In this case, the device returns an invalid status code error 
(521). 

Stalcode = $00: The device status consists of 4 bytes. The first is the general status 
byle: 

ait Function 

7 1 - Block device; - Character device 

6 1 = Write allowed 

5 1 = Read allowed 

4 1 = Device online or disk in drive 

3 1 = Format allowed 

2 1 = Media write protected (block devices only) 

I 1 ■ Device currently interrupting (supported by Apple He only) 

I I 1 = Device currently open (character devices only) 
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IF the device is a bkxA device, the next Held indicates the number of blocks in the 

device. This is a 3-bytc field for standard calls or a 4-byie field for exiended calls. The 
least significant byte is first, If the device is a character device, these bytes are set 
zero, 

Stotcode = $01: The device control block (DCB) [ 5 device dependent. The DCB is 
typically used to control various operating characteristics of a device. The DCB is set 
with the corresponding Control call. The first byte is the number of bytes in the 
control block. A value of $00 returned in this byte indicates a DCB length of 256, and a 
value oF SOI indicates a DCB length of 1 byte. The length of the DCB is always in the 
range of 1 to 256 bytes, excluding the count byte. 

Stafcode = $02: No character devices are currently implemented far use on the 
SmartPort, so the newline status is presently undefined. 

Stafcode = $03; This call returns the device information block (DIB). It contains 
information identifying the device and its type and various other attributes, The 
returned status list has the following form: 



STATUST Standard coll 



Device status byte 
Block size (low byte) 
Block size (mid byte) 
Block size (high byte) 
ID string length 
[D string (16 bytes) 
Device type byte 
Device subtype byte 
Version word 



Extended call 

Device status byte 

Block size (low byte, low word) 

Block size (high byte, low word) 

Block si2e Gow byte, ! D 

Block size ( high byte, high word) 

ID siring length 

ID string (16 bytes) 

Device type byte 

Device subtype byte 

Version word 



The device status is a 1-byte field that is the same as the general status byte returned in 
the device Status call (statcode = $00) r The block size field is the same as the block 
field returned in the device Status call. The ID string consists of 1-byte prefix 
indicating the number of ASCII characters in the ID string. This is followed by a 
16-byte field containing an ASCII string identifying the device. The most significant bit 
of each ASCII character is set to zero. 

If the ASCII string consists of fewer than 16 characters, ASCII spaces are used to fill the 
unused portion of the string buffer. The device type and device subtype fields are 
1-byie fields. Several bits encoded within the DIB subtype byte are defined to indicate 
whether a device supports the extended SmartPort interface, disk-switched errors, or 
removable media. 
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A breakdown of the DIB subtype byte is shown in Figure 7-7, 
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Subtype 
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1 1 
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stai 
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Reserved 

= Removable media 

1 = Supports disk-switched errors 
I = Supports extended SmortPort 



Figure 7-7 

SmartPort device subtype byie 

Applications requiring specific knowledge about a device should execute a DID status 
and examine the type byte. The subtype byte is used to obtain information about 
special Features a device may support. Several device types and subtypes are assigned 
to existing SmartPort devices. These types and subtypes are as follows: 

Type Subtype Device 

$00 &QQ Apple II memory expansion card 

$00 SCO Apple IIGS Memory Expansion Card configured as a RAM disk 

S01 500 UniDisk 3.5 

$01 SCO Apple 3.5 drive 

$03 $E0 Apple II SCSI with nonremovable media 

Undefined SmartPort devices may implement the following types and subtypes: 

Type Subtype Device 

Hard disk 

Removable hard disk 

Removable hard disk supporting disk-switched errors 
Hard disk supporting extended calls 
Removable hard disk supporting extended calls and disk- 
switched errors 

Hard disk supporting extended calls 
SCSI with removable media 

The firmware version field is a 2-byte field consisting of a number indicating the 
firmware version. 



Th 
co 

PC 

IT 

SC 
$2 



$02 


$20 


$02 


$00 


$02 


$ (0 


$02 


SAO 


S02 


SCO 


502 


SAO 


503 


SCO 
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irtPort driver status 

i Status call wiih a unit number of SOO and a status code of $00 is a request to return the 
atus of die SmartPort driver, This Function returns the number of devices as well as 
: current interrupt status. The format of the status list returned is as follows: 

ITL1ST Byte Number of devices 

Byte 1 Reserved 

Byte 2 Reserved 

Byte 3 Reserved 

Byte 4 Reserved 

Byte 5 Reserved 

Byte 6 Reserved 

Byte 7 Reserved 

number of devices field is a 1-byte field indicating the total number of dev:i> 
lectcd to the slot or port. This number will always be in the range to 127, 

Possible errors 

| The following error return values are possible. 

BUSERR Communications error 
J21 BADCTL Invalid status code 

S30-S3F $50-$7F Device-specific error 
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ReadBlock 

This call reads one 512-byte block from the block device specified by the unit number 
passed in the parameter list. The block is read into memory starting at the address 
specified by the daia buffer pointer passed in the parameter list 



CMDNUM 
CM DUST 



Standard call 

$01 

Parameter count 

Unit number 

Data buffer pointer (low byte) 

Data buffer pointer (high byte) 

Block number flow byte) 

Block number (middle byte) 

Block number (high byte) 



Extended call 

$41 

Parameter count 

Unit number 

Data buffer pointer Cow byte, low word) 

Data buffer pointer (high byte, low word) 

Data buffer pointer Cow byte, high word) 

Data buffer pointer (high byte, high word) 

Block number Cow byte, low word) 

Block number (high byte, low word) 

Block number Qow byte, high word) 

Block number (high byte, high word) 



Required parameters 

Parameter count Byte value = $03 

Unit number 1-byte value in the range $01 lo S7E 

Standard caH Extended call 

Data buffer pointer Word pointer (bank $00) Longword pointer 

The data buffer pointer points to a buffer into which the data is to be read. For 
standard calls, this is a word pointer into bank $00. For extended calls, the pointer is a 
longword specifying a buffer in any memory bank. The buffer must be 512 bytes long. 

Standard call Extended call 

Block number 3-byte number 4-by!e number 

The block number is the logical address of a block of data to be read. There is no 
general connection between block numbers and the layout of tracks and sectors on the 
disk. Translation from logical to physical blocks is performed by the device. 

Possible errors 

The following error return values are possible. 

306 BU5ERR Communications error 

$27 IOERROR I/O error 

S28 NODRTVE No device connected 

$2D BADBLOCK invalid block number 

$2F OFFLINE Device off line or no disk in driv« 
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WriteBlock 

The Write call writes one 512-byte block to the block device specified by the unit 
number passed in the parameter list The block is written from memory starting at the 
address specified by the data buffer pointer passed in the parameter list. 





Standard call 


Extended call 


CMDNUM 


S02 


S42 


CMDL1ST 


Parameter count 


Parameter count 




Unit number 


Unit number 




Data buffer pointer (low byte) 


Data buffer pointer Qow byte, low word) 



Data buffer pointer (high byte) Data buffer pointer (high byte, low word) 



Block number (low byte) 
Block number (middle byte) 
Block number (high byte) 



Data buffer pointer Qow byte, high word) 
Data buffer pointer (high byte, high word) 
Block number (low byte, low word) 
Block number (high byte, low word) 
Block number Qow byte, high word) 
Block number (high byte, high word) 



Required parameters 

Parameter count Byte value = $03 

Unit number 1-byte value in the range $01 to S7E 

Standard call Extended call 

Data buffer pointer Word pointer (bank $00) Longword pointer 

The data buffer pointer points to a buffer that the data is to be written from, For 
standard calls, this is a word pointer into bank $00. For extended calls, the pointer is a 
longword specifying a buffer in any memory bank. The buffer must be 512 bytes long, 



Block number 



Standard call 
3-byte number 



Extended call 
4-byte number 



The block number is the logical address of a block of data to be written. There is no 
general connection between block numbers and the layout of tracks and sectors on the 
disk. The translation from logical to physical block is performed by the device. 



Possible errors 




The following error return values are possible, 


iuf. BUSERR 


Communications error 


$27 IOERROR 


I/O error 


S28 NOD RIVE 


No device connected 


$2B NOWRITE 


Disk write protected 


$2D BADBLOCK 


Invalid block number 


S2F OFFLINE 


Device off line or no disk in drive 
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Format 

The Formal call formats a block device. Note that the formatting performed by this 
call is not linked to any operating system; it simply prepares all blocks on the medium 
for reading and writing. Opera ting-systcm-specific catalog information, such as bit 
maps and catalogs, are nol prepared by this call 



CMDNUM 
CMDLIST 



Standard call 

$03 

Parameter count 

Unit number 



Extended coil 

$43 

Parameter count 

Unit number 



Format call implementation 

Some block devices may require device-specific information at formal time. This 
device-specific information may include a spare list of bad blocks to be written 
following physical formatting of the media, in this case, it may not be desirable to 
implement the Format call so dial a physical format is actually performed because a 
spare list of bad blocks may not be available from the vendor or because of the time 
Involved in executing a bad Mode ican fi may be more desirable to implement 
device-specific Control calls to lay down the physical tracks and initialize the spare 
lists. If this latter procedure is followed, the Format call need only return to the 
application with the accumulator set to $00 and the carry flag cleared. This procedure 
should be used only when it is not desirable for the application to physically format 
the media. 



Required parameters 

Parameter count Byte value = $01 

Unit number Byte value in the range $01 to $7E 



Possible errors 

The following error return values are possible. 



$06 
S27 
S28 
S2B 
$2F 



BUSERR Communications error 

lOERROR I/O error 

NODRIVE No device connected 

NOWR1TE Disk write protected 

OFFLINE Device offline or no disk in drive 
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Control 



The Control call sends control information to the device. The in forma Lion may be 
cither general or device specific 



Standard call 



Extended cat 



CMDNUM S04 

CMDLIST Parameter count 

Unit number 

Control list pointer (low byte) 



$44 

Parameter count 

Unit number 

Conirol list pointer flow byte, low word) 
Control lisl ] h inter (high byte) Control list poinler (high byte, low word) 
Control code Control list pointer (low byte, high word) 

Control lisl pointer (high byte, high word) 

Control code 



Required porometers 



Parameter count 
Unit number 



Byte value - $03 

Byte value in the range $00 to $7E 

Standard call Extended call 



Control list pointer Word pointer (bank SOO) Longword pointer 

The control List is a poinler to the user's buffer from which the control information is 
lo be read. For the standard Control call, the pointer is a word value into bank SOO. 
For tlie extended Control call, the pointer is a longword value that may reference any 
memory bank. The first two bytes of the control list specify the length of the control 
lisj, with the low byte first. A control list is mandatory, even if the call being issued 
does not pass information in the lis). In this latter case, length of zero is used for the 
first two bytes. 



Control code 



Byte value 

Byte value in the- range $00 lo $FF 



The control code is the number of the control request being made. This number and 
ihe function indicated are device specific, except that all devices must reserve the 
following codes for specific functions: 

Code Control function 

|00 Resets the device 

$01 Sew device control block 

402 Sets newline status (character devices only) 

$03 Services device interrupt 

Coda = $00: This call performs a soft reset of the device. It generally returns 
housekeeping values lo some reset value. 
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Cod* = 501: This Control call sets the device control block. Devices generally use the 
bytes in this block to control global aspects of the device's operating environment. 
Because the length is device dependent, the recommended way to set the DCB is to 
read in the DCB (with the Status call), alter the bits of interest, and then write the same 
wring with this call. The first byte is the length of the DCB, excluding the byte itself. A 
value of 500 in the length byte corresponds to a DCB size of 256 bytes, and a count 
value of SOI corresponds to a DCB size of 1 byte. A count value of SFF corresponds to 
a DCB size of 255 bytes. 

Possible errors 

The following error return values are possible. 



506 
$21 
S22 
530-53F 



BUSERR 

HADCTL 

BADCTLPARM 

UNDEFINED 



Communications error 
Invalid control code 
Invalid parameter list 
Device -specific error 



Inrt 

The Init call provides the application with a way of resetting the SmartPort. 
Standard call Extended cai,l 

CMDNl.'M $05 $45 

CMC Parameter count Parameter count 

Unit number 



$05 

Parameter count 

Unit number 



Required poro meters 

Parameter count Byte value = $01 

Unit number Byte value = SO0 

The SmartPort will perform initialization, hard reselling all devices and sending each 
their device numbers. This call may not be made to a specific unit; rather, it must be 
made to die SmartPort as a whole. This call may not be executed by an application. 
Issuing this call in conjunction with Control Panel changes may relocate devices 
contrary to the ProDOS device list Applications wishing to reset a specific device 
should use the Control call with a control code of $00. 



Possible errors 

The following error return values are possible. 

S06 BUSERR 
S28 NODRIVE 



Communications error 
No device connected 
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Open 

The Open call prepares a character device For reading or writing. 

Note that a block device will not accept ihis call, bul will return an invalid command 
error ($01), 



CMDNUM 
CMDLIST 



Standard cad 

505 

Parameter count 

Unit number 



Extended call 

545 

Parameter count 

Unit number 



Required parameters 

Parameter count Byte value = $01 

Unit number Byte value in the range 501 to S7E 



Possible errors 

The following error return values are possible. 

Invalid command 



SOI BADCMD 
$06 BUSERR 
$28 NODRIVE 



Communications error 
No device connected 



Close 

The Close call tells an extended character device that a sequence of read or write 
operations has ended. For a printer, this call could have the effect of flushing the print 
buffer, 

Note that a block device will not accept this call, but will return an invalid command 
error C$01). 



CMDNUM 
CMDLIST 



Standard call 

$07 

Parameter count 
Unit number 



Extended call 

$47 

Parameter count 

Unit number 
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Required parameters 

Parameter count Byte value = $01 

Unit number Byte value in the range SOI to S7E 



Possible errors 

The following error return values are possible. 
BADCMD Invalid command 



soi 

S06 BUSEKR 

S28 NOD RIVE 



Communications error 
No device connecled 



Read 

The Read call reads the number of bytes specified by the byte count into memory. The 
starting address of memory that the data is read into is specified by the data buffer 
pointer, The address pointer references an address within the device mat the bytes are 
to be read from. The meaning of the address parameter depends on the device 
Involved. Although this call is generally intended for use by character devices, a block 
device might use this call to read a block of nonstandard size Ca block larger than 512 
bytes). In this latter case, the address pointer is interpreted as a block address. 






Standard coll 

CMDNUM JOg 

CMDLIST Parameter couni 

Unit number 

Data buffer pointer (low byte) 



Extended call 

848 

Parameter count 

Unit number 

Data buffer pointer (low byte, low word) 



Data buffer pointer (high byte) Data buffer pointer (high byte, low word) 



Byte count (low byte) 
Byte count (high byte) 
Address pointer (low byte) 
Address pointer (mid byte) 
Address pointer (high byte) 



Data buffer pointer (low byte, high word) 
Data buffer pointer (high byte, high word) 
Byte count (low byte) 
Byte count (high byte) 
Address pointer (tow byte, low word) 
Address pointer (high byte, low word) 
Address pointer (low byte, high word) 
Address poinier ( high byte, high word) 
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Required parameters 

Parameter count Byte value = $04 

Unit number 1-byte value in the range SOI to S7E 



Standard call 



£jtf#nd*d calt 



Data buffer pointer Word pointer (bank $00) Longword pointer 

For standard calls, this is the 2-byte pointer to a buffer into which the data is to be 
read. For extended calls, the pointer is a longword specifying a buffer in any memory 
bank. The buffer must be large enough to accommodate ihe number of bytes 
requested. 

Byte count 2-byte number 

The byte count specifics the number of bytes to be transferred. All of the current 
implementations of the SmartPort utilizing the SmartPort Bus have a limitation of 767 
bytes. Other peripheral cards supporting the SmartPort interface may not have this 
limitation. 



Address pointer 



Standard call 

3-bvte address 



Extended call 
4-byte address 



The address is a device-specific parameter usually specifying a source address within 
the device. Thi& call might be implemented with in extended block device using uw 
address as a block address for accessing a nonstandard block. For example, such an 
implementation allows the Apple 3-5 drive and UniDisk 3.5 drive to read 524-byte 
Macintosh blocks from 3. 5-inch media. 

Possible errors 

The following error return values are possible. 



m 


BUSERR 


Communications error 


527 


TOERROR 


I/O error 


m 


NO DRIVE 


No device connected 


S2B 


NO WRITE 


Disk write protected 


52 D 


BADBLOCK 


Invalid block number 


S2F 


OFFLINE 


e off line or no disk in drive 
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Write 



The Write call writes [he number of bytes specified by the byte count to the device 
specified by the unit number. The starting memory address thai the data is read from 
is specified by the data buffer pointer. The address pointer references an address 
within the device where the bytes arc to be written. The meaning of the address 
parameter depends on the device involved. Although this call is generally intended 
for use by character devices, a block device might use this call to write a block of a 
nonstandard size (a block larger than 512 bytes). In this latter case, the address field is 
interpreted as a block address. 



Standard coll 

CMDNUM $09 

1 :Ml:it.lS1 f',r:irra-kT (yffl 

Unit number 

Data buffer pointer (low byte) 



Extended coll 

S49 

Parameter count 

Unit number 

Data buffer pointer Clou byte, low word) 



Data buffer pointer (high byle) Data buffer pointer (high byte, low word) 



Byte count (low byte) 
Byte count (high byte) 
Address pointer (low byte) 
Address pointer Cmid byte) 
Address pointer (high byte) 



Data buffer pointer Cow byte, high word) 
Data buffer pointer (high byte, high word) 
Byte count Clow byte) 
Byte count (high byte) 
Address pointer (low byte, low word) 
Address pointer (high byte, low word) 
Address pointer (low byte, high word) 
Address pointer ( high byte, high word) 



Required parameters 

Parameter count Byte value = $04 

Unit number 1-byte value in the range SOI to $7E 
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Standard call 
Data buffer pointer Word pointer (bank 



Extended call 
Longword pointer 



For standard calls, this Ls the 2-byte pointer to a buffer into which the data is to be 
read For extended calls, the pointer is a longword specifying a buffer in any memory 
bank. The buffer must be large enough to accommodate the number of bytes 
requested. 



Byte count 



2-byte number 



The byte count specifies the number of bytes to be transferred All of the current 
implementations of the SmanPon utilizing the SmanPort Bus have a limitation of 767 
bytes, Other peripheral cards supporting the Smart-Port interface may not have this 
limitation. 



Address pointer 



Standard call 
3-byic value 



Extended call 
4-byte value 



The address is a device-specific parameter usually specifying a destination address 
within the device. This call might be implemented with a block device, using the 
address as a block address for accessing a nonstandard block. For example, such an 
implementation allows the Apple 3.5 drive and UniDisk 35 drive to write 524-byte 
Macintosh blocks to 3- 5-inch media. 

Possible errors 

The following error return values are possible. 
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BUSERR 


Communications error 


$27 


IOERROR 


I/O error 


$28 


NODKlVh 


No device connected 


S2B 


NQWRITE 


Disk write protected 


$2D 


BADBLOCK 


Invalid block number 


$2F 


OFFLINE 


Device off line or no disk in drive 
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Tables 7-2 and 7-3 summarize the command numbers and parameter lists for standard 
and extended SmartPort calls. 



r, 



Tab!* 7-2 

Summary of standard commands and parameter lists 



Command Status ReadBloch WritvBlock Format Control Inll 



Open Close Read 



Write 



CMDNtM 

CMDLIST 
byte 



1 



$00 



$03 

Unit 
number 

Slat us 

list 

pointer 

Status 

list 

pointer 

Status 
code 



$01 



$03 

Unit 
number 

Date 

buffer 

pointer 

Data 

buffet 

pointer 

Block 
number 

Block 
number 

Block 
m imhnr 



soz 



503 

Unit 

number 

Data 

buffer 

pointer 

Data 

LiulTcr 
pointer 

Block 

number 

Block 
number 

n 1 1 m hip r 



$03 



$01 



|04 



$03 



505 



S01 



506 



501 



$07 



$01 



SOS 



$04 



509 



$04 



Unil Unit Unit Unit Unit Unit Unit 

number number number number number number number 

Oomrol 

list 

pointer 

Control 

list 

pointer 

Control 

code 



Data 

buffer 

pointer 


! ill, 

buffer 
pointer 


. Ml.. 

buffer 
pointer 


Data 

buffer 

pointer 


Byte 

count 


Byte 
count 


Byte 

, -V..-V 


re- 
count 



* This parameter Ls device specific. 

♦ Note.- The Read byte count, and Ihe Control call list contents in some SmartPort implementations 
may not be larger than 767 bytes. 

Upon return from the Read call, the byte count bytes will contain the number of bytes actually read 
From the device. 
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Table 7-3 


























Summary of extended commands and parameter lists 














Command 


Status 


RecdBlock 


Write! lock 


Format 


Control 


trill 


Open 


Close 


R«od 


Writs 




CMDNTJM 


$40 


$41 


$42 


*43 


$44 


$45 


$46 


$47 


$48 


$49 




CMDLIST 


























byte 





























$03 


$03 


$03 


SOI 


$03 


soi 


SOI 


SOI 


$04 


S04 




i 


Unit 


Unit 


[In* 


Unit 


Li in. 


Unit 


Link 


Unit 


Unit 


Unit 






number 


number 


number 


n umbei 


number 


number number 


numbei 


number 


number 




2 


Status 


Data 


Data 




Control 








Data 


Data 






list 


buffer 


buffer 




list 








buffer 


buffer 






pointer 


pointer 


pointer 




polntci 








pointer 


pointer 




3 


Status 


Data 


Data 




Control 








i )wa 


>j .i 






list 


buffer 


buffer 




list 








buffer 


buffer 






pointer 


pointer 


pointer 




pointer 








pointer 


pointer 


4 


Status 


Data 


Data 




Control 








: lata 


Data 




list 


buffer 


buffer 




list 








buffet 


buffer 




pointer 


pointer 


pointer 




pointer 








poinu-r 


pointer 




5 


Status 


Data 


Data 




Control 








Data 


Data 






list 


buffer 


buffer 




List 








buffer 


buffer 






pointer 


poinier 


[>. ink r 




poilltcl 








pointer 


pointer 




6 


Status 


Block 


Block 




Control 








Byte 


Byte 






code 


number 


n u rr be r 




code 








count 


count 


7 




Block 

nuriU-r 


Block 
number 












Byte 
counl 


Byte 

count 


8 




Block 

number 


Block 

number 












- 


■ 


9 




Block 


Block 












■ 


• 


1C 




number 


numbcT 












* 


r 




n 

| ' This parameter is device specif] 


c 












i 


■ 




♦ rV&fft The Read byte count and the Control call list contents in . 


some SmartPort im 
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Device-specific SmartPort calls 

In addition 10 the common command set of SmartPort calls already listed, a device 
may implement its own device-specific calls. Usually, these calls are implemented as a 
subset of ihe SmartPort Status or Control call rather than as new commands. 



SmartPort calls specific to Apple 3.5 disk drive 

Seven Apple 3.5 drive device-specific calls are provided as extensions to the Control 
call. These device-specific control calls may be used only with the Apple 3.5 drive. To 
determine whether a device is an Apple 3 5 drive, examine the type and subtype bytes 
returned from a DIB status call. If the type byte is returned with a value of SOI and the 
subtype byte is returned with a value of SCO, then the device is an Apple 3.5 drive. 
Because device-specific calls to the Apple 3.5 drive are implemented as Control calls, 
only the control code and control list for these calls are defined here. Refer to the 
SmartPort Conlrol call section earlier in this chapter for information about the 
command byte and parameter lisi. 

The following information about Eject and SetHook should be treated as an extension 
to the extended SmartPort Control call. 



Eject 

ejects the media from a 3.5-inch drive. 
Control code Control list 



$04 



Count low byte 
Count high byte 



V 
M< 

$' 

IV 

J 

$ 

s 

s 

$ 



SetHook 

SetHook redirects routines internal to the Apple 3,5 drive. The routine to be 
redirected is referenced by the hook reference number. The address that the routine is 
to be redirected to is specified by the 3-byte address field is\ rite control list- 



Control coda 


Control list 




505 


Count low byte 


$04 




Count high byte 


soo 




Hook reference number 


$xx 




Address low 


Sxx 




Address high 


Sxx 




Address bank 


Sxx 
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Valid hook reference numbers and their associated routines are as follows: 



Hook 




rtference 


Routine 


$31 


Read Address Field 


$02 


Read Data Field 


$03 


Write Data Field 


$04' 


Seek 


$05 


Format Disk 


$06 


Write Track 


$07 


Verify Track 



Read Address Field 

Tie Read Address Field routine reads bytes from the disk until it finds Lhe address 
marks and a sector number specified as input parameters for the routine. The Read 
Data Field routine reads a 524-byte Macintosh block or 512-byte Apple II block from 
the disk. 



Write Data Field 

The Write Data Field routine writes a 524-byte block of data 10 the disk, For Apple II 
blocks, the first 12 bytes will be written as zero. 



Seek 

The Seek routine positions the read and write head over the appropriate cylinder on 
the disk 






Format 

'the Format routine writes address marks, data marks, zeroed data blocks, checksum, 
and end-of-block marks, 



Write Track 

The Write Track routine is called by lhe formatter to write one track of empty blocks. 
The number of blocks written depends on the track that the read and write head is 
positioned over. 
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Figure 7-8 demonstrates the physical layout of the format that this command writes. 
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Figure 7-S 
Disk-sector format 



Verify 

The Verify routine is called by the formatter ta verify thai ihe data written by the Write 
Track routine was written correctly. 



ResetHook 

ResetHook restores the default address for the hook specified in the control list. 



Control code 
$06 


Control llsf 

Count low byte 

Count high byte 

Hook reference number 


501 
$00 



Set Mark 

SetMark changes individual bytes in the mark tables. The count field specifies the 
number of bytes in the mark table to be written plus 1. The start byte references an 
offset into the nwk labte to w4\ich the new bytes are to be written. Bounds checking is 
performed to make sure the byte count does not overflow the internal mark table. 



Control cod* 


Control list 




$07 


Count low byte 


$xx 




Count high byte 


$00 




Start byte 


Sxx 
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The default values for the Mark table are as follows; 



Value Bylc number 



Value Byte number 



JFF 


sector number 


$AA 


n 


$AD 


1 data marks 


SDE 


12 


SAA 


1 


$FF 


13 


$D5 


3 


$FF 


14 interheadcr gap 


Sff 


4 


JFF 


15 


SFC 


5 sync bytes 


$FF 


16 


3F3 


6 


SFF 


17 


$CF 


■ 


390 


18 address marks 


$3F 


8 


$AA 


19 


SFF 


9 


$D5 


20 


$FF 


10 bit-slip marks 


SFF 


1: 


ResetMark 







ResetMark restores individual bytes in the mark tables to the default values. The count 
field defines the number of bytes in the mark table to be restored plus 1. The start field 
defines where in the mark table the bytes are to be restored, 



Control cod* Control list 

508 Count low byte Sxx 

Count high byte $00 

Start byte Sxx 



Sets Ides 

SetSides sets the number of sides of the media to be formatted by the Format call. It 
supports both single-sided and double-sided media. If the most significant bit of the 
number of sides field is sel to 1, then double-sided media are formatted. If the most 
significant bit is cleared to 0, then single-sided media are formatted. 



Control code Control list 

$09 Count low byte $04 

Count high byte $00 

Number of sides Snn 



Setlnterleave 

Setlnterleave sets the sector interleave to be layed down an die disk by the Format call. 

Control code Control list 

S0A Count low byte SO0 



Count liigh byte 
Interleave 



S00 

S01 to S0C 
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SmortPort calls specific to UniDisk 3.5 

Five UniDisk 3.5 device-specific calls arc provided as extensions lo the Control and 
Status calls. These device-specific calls may be used only with the UniDisk 3.5. To 
determine whether a device is a UniDisk 3 5, examine ihe type and subtype bytes 
returned from a DIR status call. If the type byte is returned with a value of SOI and ihe 
subtype byte is returned with a value of $00, then the device is a UniDisk 3-5- Only the 
control code and control list are defined for calls here implemented as extensions to 
the Control call, For calls implemented as extensions eo the Status call, only the status 
code and status list are defined. Refer to the sections discussing the SmartPort Control 
and Status calls earlier in this chapter for more information about these calls. 



Eject 

Eject ejects the media from a 3-5-inch drive- 
Control code Control list* 
$04 Count low byte $00 



Count low byte 
Count high byte 



$00 



Execute 

Execute dispatches the intelligent controller in the UniDisk 3.5 device to execute a 
65C02 subroutine. The register setup is passed to the routine to be executed from the 
control list. 



Control code 


Control list 




$05 


Count low byte 


$06 




Count high byte 


$00 




Accumulator value 


$xx 




X register value 


$xx 




Y register value 


$xx 




Processor status value 


$xx 




Low program counter 


5 xx 




High program counter 


Sxx 
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Set Address 

SetAddress sets the address in the UniDisk 3-5 controller memory space into which the 
Download call loads a 65C02 routine. The download address must be set to free space 
in the UniDisk 3-5 memory map. 

Control cod* Control lis) 

$06 Count low byte $02 

Count high byte $00 

Low byte address $xx 

High byte address Sxx 



Download 

Download downloads an executable 65C02 routine into the memory resident in the 
UniDisk 3.5 controller. The address thai the routine is loaded into Ls set by the 
SetAddress call. The count field must be set to the length of the 65C02 routine to be 
downloaded. 



Control cod* Control list 

$07 Count low byte 

Count high byte 
Executable 65C02 routine 



$xx 

$xx 



UniDiskStat 

UniDiskSiat allows an application to get more information about an error that occurs 
during a read or write operation. It also allows an application to access the 65C02 

register state after dispatching the UniDisk 3.5 controller to execute a 65C02 routine via 
the Execute call. 

Memory- mapped I/O addresses internal to the UniDisk 3-5 controller are shown in 
Figure 7-9 and Tables 7-4 and 7-5. 



St a 1 us cod* 


Status lint 




$05 


Byte 


$04 




Soft error 


soo 




Retries 


Sxx 




Byte 


SOO 




A register after execute 


Sxx 




X register after execute 


Sxx 




P register after execute 


Sxx 
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UniDisk 3.5 internal functions 

Copy protecting a UniDisk 3-5 is more complicated lhan protecting a Disk U because 
the 3.5-inch disk has its own controller. The drive Itself (beyond the small 65C02 
system that controls it) is somewhat intelligent; performing such operations as 
stepping the drive to a half track is not possible with the double-sided Sony disk. 

The design of the UniDisk 3.5 firmware, however, affords the copy- protection 
engineer (CPE) tools with which to alter the data on the disk sufficiently to make 
copying very difficult. In all cases, code or other information Ls downloaded to the 
controller's on-board RAM, The firmware provides a defined method for setting 
RAM, but not for reading it; this increases the difficulty of the copy-protection buster's 
job. Information downloading is accomplished using the Set_Down_Adr and the 
Download commands, detailed in the SmaxLPort documentation. 

Further, running nibble-copy programs with the UniDisk 3,5 is difficult to do. Nibble- 
copy programs typically dump an entire track into memory and then try to make sense 
of what they have read and duplicate the data stream. The UniDisk 3.5 controller 
COOtaios only 2K of RAM, and this limitation makes track dumping and copying 
extremely difficult. A track would have to be dumped in 1 or 2K pieces, and then the 
pieces would have to be correctly reassembled, processed in host memory, and 
somehow written in 1 or 2K pieces to the target disk. CFhe difficulty of creating a 
reasonable bit copier means that elaborate copy-protection measures may not be 
necessary and that relatively simple techniques, such as simply changing marks, will 
suffice,) 




Mark table 



All address and data marks used by the RdAddr, ReadData, WriteData, and Format 
routines are located in page zero. The following details the table values and their 
functions (note that these tables are all reversed from the order in which they appear 
on the disk): 



Function 


Address 


Default value 


Data marks 


5008E 


$AD r SAA, $D5 


Daia-synt marks 


S0091 


$FF, $FC, SF3, $CF. $3F, $FF 


Bit slip marks 


S0097 


$FF, $AA, SDE 


Address marks 


S0O9F 


$96, 5AA, $D5 



The CPE can alter the values in this table and format a disk with the new marks, and 
read and write operations will recognize sectors with these new marks. 
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The CPE must, however, be careful when changing the marks. The address, data, and 
bit-slip marks were chosen so that no bytes in the user's encoded data could be 
mistaken for them, and the CPE should consider this when changing the marks. 
Probably the safest marks to alter are the bit-slip marks because Ihe firmware never 
uses these to try to find a field, they are simply double checks to ensure that 
Synchronization was maintained during a read operation. 

The data-sync marks could conceivably be altered and some identifying mark used 
instead. The CPE should be aware, however, that this Held is partially rewritten every 
time the block is written and that whatever marks are there must guarantee the 
synchronization of the IWM so that the first data-field mark (normally $D5) can be 

mad 



Hook table 

Each major disk-access routine has a JMP instruction to jump through a hook in zero 
page. Hooks in these routines are collected in a section of zero page known as the hook 
table, Each hook is a 3-byte 65C02 JMP instruction that vectors to the corresponding 
routine. This allows the CPE to install routines to take the place of ones such is RdAddr 
and ReadData. Because the hooks are reset when power up occurs or a reset control 
all is issued, the CPE may preserve the "default" address in a hook, point the hook at 
his or her own routine, and then have this new routine end by jumping to the old 
routine. This in effect allows the CPE to insert tn his or her own code at strategic points 
in the disk read and write processes. 

The CPE must ensure that any code installed in place of a routine emulates the 
behavior of the code it replaces. The functional and flag return specifications for the 
routine must be obeyed-, otherwise, higher-level routines will become confused. The 
'bookable" routines are as follows: 

Add/ess Vector Routine function 

50072 RdAddr Find and decode an address field 

S0075 ReadData Find and load a data field into RAM 

50078 WriteData Write data-sync field marks, data, bit-slip marks 

$007B Seek Turn motor on and seek the specified track 

S007E Formal Write address and data fields (all zeros) 

$0081 WritcTrk Seek head and write track full of sectors 

$0084 Verify Verify the integrity of an entire track 

$0087 Vector Dispatch a command received from the host 

Specifications for each of these routines follow. Note that you will be able to use these 
functions more effectively if you understand the 35-inch disk data format. 

I TPhen bits of bytes arc specified, they are numbered 76543210 and enclosed m 
brackets [ ]. Also, note that the controller supports two drives Cdrive and drive 1), 
even though all UniDisks 3-5 use a single-drive configuration (drive only). 
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UniDisk 3.5 interna! routines 



RdAddr 

Find and decode an address field, 



Output 



Carry set on timeout, checksum, or bit-slip error, clear otherwise. 

Sectlnfo (5 byte*) at $0027 (if carry clear). 

On error: $0057[51 is set, meaning address error. 

None. A, X, V are not preserved. 



Register 
requirements 

This routine waits for the /READY line to go low and then waits for an address field to 
spin by, A timeout of almost two sector times is allowed. If no address mark is found 
during this period, or if the data in the address field has a bad checksum, or if ihe bit- 
slip bytes are wrong, ihe routine returns with the carry flag set If the carry flag is set, 
then the status byte has the address error bit set. If a good address field was read, its 
contents are denibblized and the results left in $27-$2B in reverse order from die way 
they appear on the disk. 






ReadData 

Find and load a data field into RAM. 



Output 



Carry set if timeout, checksum, or bit-slip error; clear otherwise. 

Data read into buffers at SlOO, S640, and $740. 

On error: $0057E31 set for bit slip, [41 set for checksum error. 



Register 

requirements None. A, X, Y are not preserved. 

This routine searches for marks identifying a data field. This routine is called 
immediately after a successful call to RdAddr; therefore, the timeout is extremely 
short (25 bytes), After a data-field mark is found, the next byte is denibblized and 
checked to see if it has (he correct sector number, and an error is returned if it does 
MX if the header is all right, the data is read, decoded on the fly, and placed in the 
three data buffers in reverse order. The bit-slip marks are checked, and an error is 
generated if they are not as expected, If an error occurs, the status byte $0057 is set to 
indicate the type of error encountered. 






Chapter 7: SmartPort Firmware 



WrireData 

Write data syne field, marks, data, bit-slip marks. 

Input Data in buffers at $100. $640, and $740; checksum. 

Register 

requirements None. A, X, Y are not preserved. 

This routine is called just after RdAddr has found the correct address field, li writes out 
the data-sync field, the data marks, the nibblized sector number, the data, and die bit 
slip marks. At this point, checksumming and pump priming will already have been 
performed by the WritePrep routine. 



Seek 

Turn motor on and seek the s 



track. 



Input 



Output 



Cyl ($14): new cylinder ($Q0-$4F) to seek. 

Drive (£13): drive currently selected. 

CurCyl (SOD, $0E): cylinder where each head initially tests. 

Carry set if seek error, clear otherwise. 
CurNSect C$1 A): number of sectors this cylinder. 
On error.- $005711] set for seek error. 

Ister 
requirements None. A, X, Y are not preserved. 

If CurCyll7] for this drive is set, the routine recalibrates the head The motor is turned 
on, the stepping direction is set, and the correct number of step pulses is issued. 






Format 

Write address and data fields (all zeros). 
Input 



Output 



Drive ($13): drive currently selected 

FormSides ($63): format a double-sided disk (580), 

Carry set if error; dear otherwise. 
On error: $005E has $A7 error code. 



Register 

requirements None, A, X, Y are not preserved 

The formatter turns on the motor and checks whether a write-enabted disk is in the 
drive. If one is, a sector image is generated and WriteTrk is called. Then Verify is 
called, if verification fails, up to 10 retries are attempted. If FormSides is set to double 
sided ($80), both heads are formatted before the head is stepped to the next track. 
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WriteTrk 

Seek head and wrile track full of sectors. 

Input Drive C$13): drive currently selected. 

Cyl CS1.4): cylinder to format. 
Side ($16): head number, 

FormSides ($63): format a double-sided disk CS80). 
Interleave ($62): set physical interleave. 

Register 

requirements None. A, X, Y are not preserved, 

This routine seeks the head (if necessary), writes a large group of sync marks (to 
guarantee the entire track), and then writes the appropriate number of sectors with the 
correct interleave. 



Verify the integrity of an entire track. 

Input CurNSect ($1A): number of sectors this cylinder. 

Output Carry set if error; clear otherwise. 

On error: 50057 bits are set specifying error. 

Register 

requirements None. A, X, Y are not preserved. 

This routine uses RdAddr and RcadData to verify that all sectors on the track are all 
right, that sectors are unique and that the data fields can be read without error. 
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Vector 

Dispatch a command received from the host. 

Input CmdTab (S4C$54): command from SmartPort. 



Output 



StatusTab ($56\.$5B); sec to $00. 

StalByte ($5E): $80 for no error-, error code otherwise 



Register 

requirements None A. X, Y are not preserved 

This routine looks in ihe command table, checks the validity of the command code 
and parameter count, turns on the drive specified, and jumps to the routine thai 
services the type of command specified. It also sets up the default parameters for the 
communication routines. If an error is detected in the parameter count or command 
code, the status byte is set appropriately. The command table looks like this: 

CMDTab 
CMDPCount 

CMDRemain 

The contents of the last 7 bytes depend on the call type. They are the bytes after the 
unit number in the SmartPort command list 



DFB 


Command_Code 


,0 - status, 1 = read, etc 


DFB 


Parameter Count 


-.Logical count for this command 


DS 


0,7 


.Call specific 
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Memory allocation 

The firmware does not use page 5 of RAM or ihe lop 64 bytes Ql the aero page. The CPE 
is Free to Install patches and other code in $0500-$O5FF and $0OCO-S00FF Figure 7-9 
shows the entire UniDisk 3-5 memory map as well as firmware RAM space use. 



Memory layout 
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V 












Table 7-4 










UnlDisk 3.5 


gat© array I/O locations 






Function 


data* data3 


dafa2 data] dataD 


Read S800 


LASTONE/ BUSEN/ 


WRREQ /GATENBL HDSEL 




Wrt$800 


TRIGGER ENBUS 


PH3EN IWMDIR HDSEL 






Read S801 


SENSE BLATCH1 


BLATCH2 URONEN CAO 






WrtSSOl 


/RST1WM /B LATCH 


/BLATCH DRIVE1 DRIVE2 






Table 7-5 


CLR1 


CLR2 






UniDJsk 3.5 IWM locations 






location 


Specific label 


IWMDIR = (drv> IWMDIR - 1 (host) 


$0A00 


PHASED resei 


CAO reset /BSY handshake 




J0A01 


PHASED set 


CAO set /BSY handshake 






SOA02 


PHASE1 reset 


CA1 reset 






$0AO3 


PHASE! set 


CA! set 






J0AO4 


PHASE2 reset 


CA2 reset 






S0AO5 


PHASE2 set 


CA2set 








S0A06 


PHASES reset 


LSTRB reset 








S0A07 


PHASES set 


LSTRB set 






S0A08 


MOTOROFF 








$OA09 


MOTORON 








$0AOA 


ENABLE] 








«r, ■ OB 


CM --<-!> tno 








SOAOC 


L6 reset 








SOAOD 


L6set 








SOAOE 


L7 reset 










$0AOF 


L7sct 
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ROM disk driver 

'Hie ROM disk is a plug-in card that houses ROM that may be organized into blocks to 
emulate a disk device or provide space for ROM-based programs. Although the 
SmartPort has no built-in ROM disk, SmartPort does support an external ROM disk 
driver. 



Installing a ROM disk driver 

The driver for a ROM disk must reside at address SFO/OQQQ. The ROM disk may occupy 
only the address space from $FO/000O through $F7/FFPF, The base address of the 
driver must contain the ASCII string ROMDISK in uppercase letters with the most 
significant bit on. Entry to the ROM disk driver is through address $F0/G007. The 
SmartPort firmware will search for a ROM disk driver during the boot process while 
assigning unit numbers to each oF the SmartPort devices, If the SmartPort finds the 
ASCII string ROMDISK at address $FQ70007, it executes an Initialization call to the 
ROM disk driver via the ROM disk entry point. If the ROM disk returns with no error, 
the ROM disk driver is installed in the SmartPort device chain. If the ROM disk 
Initialization call returns an error, the ROM disk driver is not installed in the SmartPort 
device chain. Note that the ROM disk driver is called via a JSL instruction in 8-bit 
native mode. 



Passing parameters to a ROM disk 

Call parameters are passed to the ROM disk from the SmartPort through fixed memory 
locations in absolute zero page. All input to device-specific drivers is passed in an 
extended format, even for standard SmartPort calls, so that the call parameters can 
always be found in fixed locations. Note that standard calls are not changed into 
extended calls-, only parameter organization is affected. 

Some parameters do not occupy contiguous memory when they are presented in an 
extended format because the order of parameters has been prepared so the 
parameters can be transmitted over the SmartPort bus to intelligent devices. Absolute 
zero page locations $40 to 62 arc saved by the SmartPort prior to their dispatch to the 
ROM disk and are restored by the SmartPort after their return from the driver. Thus, 
these locations are available for use by the ROM disk driver. 
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Call parameters are passed to the ROM disk driver as follows: 




Location Parameters Call typo 




1 $42 Buffer address (bits to 7) All 




$43 Buffer address (bits 8 to 15} All 


1 $44 Buffer address (bits 16 to 23) All 




$45 Command All 




$46 Parameter count All 




1 $47 Buffer address (bits 24 to 3D All 




$48 Extended block (bits to 7) ReadBlock and WriteBlock 




Status code or control code Status and Control 




Byte count (bits to 7) Read and Write 




I $49 Extended block (bits 8 to 15) ReadBlock and WriteBlock 




Byte count (bits 8 tol5> Read and Write 




S4A Extended block (bits 16 to 23) ReadBlock and WriteBlock 




Address pointer (bits to 7) Read and Write 




$4B Extended block Cbits 24 lo 3D ReadBlock and WriteBlock 




Address pointer (bits 8 to 15) Read and Write 




S4C Address pointer (bits 16 to 23) Read and Write 




S4D Address pointer (bits 24 lo 31) Read and Write 




Parameters returned to the application from the ROM disk driver are passed in 


absolute zero page locations as follows: 


location Output poromotor passed 




j 5OOO05O Error code 




500005 1 Low byte of count of bytes transferred to host 




, 5000052 High byte of count of bytes transferred to host 




All I/O information passed between the application making the SmartPori call and the 




ROM disk driver is passed through the buffer specified in the parameter list, 
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ROM organization 

ROM for a ROM disk must contain the ROM disk signature string as well as a ROM disk 
driver. A map oFthe ROM address space when portions of ROM are organized as 
blocks is shown in Figure 7-10. 



• • 


• • 


< 


> * 




ROM disk blocks 


SFn/XXXX+1 




SFn/XXXX 






ROM disk driver 


S F00007 




SF00000 


ACSII string 'ROMDISK - 


Figure 7-10 

The ROM disk 
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A block diagram of a ROM disk that occupies 12BK of ROM (including the driver itself) 
is shown in Figure 7—11. Note that no ROM space has been reserved for toolset 
expansion in litis example. 
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Summary of SmartPort error codes 

SmartPort error codes are summarized in Table 7-6. 



Table 7-6 

SmarfPort 



error codes 



Ace valu* Error r/p» 



Description 



soo 


No error 


$01 


BADCMD 


$04 


BADPCNT 


$06 


BUSERR 


$11 


BADUNIT 


$1F 


NOINT 


$21 


BADCTL 


522 


BADCTLPARM 


$27 


lOERROR 


$28 


NODRIVE 


$2B 


NOWRITE 


$2D 


BADBLOCK 


$2E 


DISKSW 


$2F 


OFFLINE 


530-53F 


DEVSPEC 


54Q-54F 


RESERVED 


55Q-55F 


NONFATAL 


560-S6F 


NONFATAL 



No error occurred. 

A nonexistent command was issued. 

A bad call parameter count was given. This error 
occurs only when the call parameter list is not 
properly constructed, 

A communications error occurred in the 1WM, 

An invalid unit number was given. 

Interrupt devices are not supported. 

The control or status code Is not supported by the 
device. 

The control list contains invalid information, 

The device encountered an I/O error. 

The device is not connected This error can occur if 
the device is not connected but its controller is, 

The device is write protected, 

The block number is not present on the device. 

Media has been swapped (extended calls only). 

The device is ofF line or no disk is in drive. 

These are device-specific error codes. 

Reserved for future use. 

A device-specific soft error occurred. The operation 
was completed successfully, but an abnormal 
condition was detected. 

These errors are the same as the errors in the $20-$2F 
range. Bit 6 indicates a soft error. 
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The SmartPort bus 

The SmartPort bus is a daisy chain configuration of intelligent devices, sometimes 
called bus residents, connected to the disk port oF the host CPU. A Disk II device may 
be physically connected to the end of the SmanPori device chain on the Apple IIGS, 
and its operation will be transparent to the host firmware. The Disk II device is 
dormant when a SmartPort bus resident is addressed. The number of bus residents that 
can be supported is limited by supply- power and IWM-drive considerations. Although 
trie software supports up lo 127 bus residents, power requirements usually limit the 
maximum number of residents to 4. 

Drive selection is performed through the firmware. The command string contains a 
byte specifying the device to be accessed. These device ID bytes are assigned by the 
SmartPort at bus reset, 

Two functions are stricdy hardware invoked: bus reset and bus enable. Doth of diese 
mrvNtinrn; vrt* invoked Thrmioh rnmhifUlfinns of r«hfl<w* J«np<i on rhp disk nnrt thai 

never occur under normal Disk II operation (Both functions involve invoking 
opposing phases, which is pointless on a Disk n.) This allows a Disk II device and Other 
bus residents lo stay out of each other's way. The bus reset and enable functions are 
summarized below, 

PHI PHO 

1 X 

1 

The state of the PHO line during the enable function can be either a 1 or a because 
PHO is used as a KEQ handshake line cycled on a packet basis when the bus is enabled- 
ACK is sensed from the device through the IWM wriie-protect sense status. 



Function 


PH3 


p^ 


Enable 
Reset 


1 




X 

1 



How SmartPort assigns unit numbers 

The assignment of unit numbers is initiated by executing a call to the slot 5 boot entry 
point 'this assignment always begins with a bus reset. The reset flips a latch on all bus 
residents, which causes the daisy-chained phase 3 line to became low. This makes all 
daisy-chained devices incapable of receiving the bus-enable signal, which requires 
se 3 to be high. 



The host then sends the ID definition command. Whenever a device receives this 
command (with Enable), it assigns the unit number embedded in the command slnng 
as its own unit number. Thereafter it will not respond to any command suing with a 
unit number other than that given it in the ID definition command, 
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Upon completing the ID definition command, the bus resident reenables ihe phase 3 
line, allowing the next resident to receive its ID definition command. This process 
continues so long as there are bus residents. 'Hie last bus resident in the device chain 
returns an exception, indicating thai it is the last bus resident. 

Although Disk n devices are connected lo Lhe disk port, they are not bus residents and 
do not respond to the ID definition command. A resident determines that it is the last 
intelligent device in the chain by sensing a signal, normally unused in Disk II 
operations, which is grounded by all intelligent devices. IF no bus resident or Disk n 
device is daisy chained to the port, the phase 3 line is read as high. 



SmartPort-Disk fl interaction 

The disk port built into the Apple IIGS supports daisy-chained 5.25-inch disks OJniDisk 
5.25, Disk II, or DuoDisk) by sharing the same disk port hardware between two 
different ROM slot areas. The slot 5 ROM area contains the SmartPon interface and 
ProDOS block device driver, and the slot 6 ROM area contains the Disk II interface. 
The Disk II device is enabled by the disk port signal /ENABLE2, The SmartPon must 
activate the /ENABLE2 line to communicate with intelligent bus residents, Ff this line 
were not intercepted before being passed to daisy-chained devices, any attempt to talk 
to devices on the bus would result in spurious operation of the Disk II at the end of the 
chain. 

For the Disk II to remain aloof from SmartPon activity, each resident must gate the 
/ENABLE2 line so that whenever any SmartPon bus resident is enabled (PIIASE1 and 
PHASE3), any Disk II at the end of the chain is disabled. In other words, the 
/ENABLES line is passed to daisy-chained devices only when either PHASE] or 

N IASE3 is low: 



BUS ENABLE (PHI and PH3) 

PHASE1=0 or PHASE3=0 
PHASE1-1 and PHASE3=1 



/ENABLE2 (doiiy chained) 

/ENABLE2 
Deasserted (high) 



Other considerations 

All intelligent residents try to process every command packet sent over the bus; a 
resident responding only if it recognizes its own ID, type, and subtype encoded in the 
packet. The device type and command are used by the device to arbitrate between 
extended and standard packets. Thus, one resident can tell when some other resident 
is being accessed or if the packet type (extended or standard) is compatible with the 
device, A device controller can therefore reduce its power consumption when it is not 
being constantly accessed. 
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Extended and standard command packets 

The number of bytes passed over the SmartPort bus in a standard command packet is 
ihe same as the number contained man extended command packet Standard 
SmartPort command parameter lists can consist of up to 9 bytes- Extended SmartPort 
command parameter lists can consist of up to 1 1 bytes. The command packet was 
designed for a maximum of 9 bytes of information. The first 2 bytes always contain the 
SmartPort command number and parameter count. Trie remaining 7 bytes consist of 7 
bytes of the parameter list starting with Ihe tfiii for standard commands or the 

fifth byte for extended commands; 7 bytes from the parameter lis) always are copied 
into the command packet, even though the parameter lest for the current command 
may consist of fewer than 7 bytes. 



SmartPort bus flow of operations 

The general flow of control in the SmartPort is illustrated in Figure 7-12. 



ProDOS Interface 



Packet rranagemerir 



D- 



Disk port 



'STiaMPo'1 bjs 



SmartPort mte'face 



Rgure 7-12 

SmartPort control flow 

Whenever a call is made to the SmartPort device driver that uses the SmartPort bus, 
ihe command table sent to the device driver is converted into a command packet 
before being sent to the device. The results of the call are also sent back from ihe 
device in a packet. All data sent over the bus is placed in these packets. 

$ Note: Each byte of the packet is a 7-bit quantity (bit 7 is always set), a limitation 
imposed by the IWM. All data sent is converted from 8-bit quantities to 7-bit 
quantities before transmission. 

The information of the packet can be broken down into the following categories: 

a general overhead 

n source and destination IDs 

□ contents type and auxiliary (aux) type 

a contents scams 

a contents 
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The identifiers arc 7-bit quantities assigned sequentially according to the device's 
position in the chain. The host is always ID=0. Because every byte in the packet has the 
most significant bit set, the host is $80, the first device in the chain is $81, and so on. 

The contents type consists of a type and aux type byte Three contents types are 
currently defined: Type = S80 Ls a command packet, type = 581 is a status packet, and 
type = S82 is a data packet. Bit-6 is the command byte, and the aux type byte defines 
the packet as either extended or standard, Aux type = $80 indicates a standard packet, 
and SCO indicates an extended packet. Command = SBX indicates a standard packet, 
and SCX indicates an extended packet. 

The contents byte is used for status and data packets. It contains the error code for read 
and write operations. The SmartPort returns the contents byte as an error code for the 
call. 

The contents itself consists of bytes of 7 bits (high bit set) of encoded data. Preceding 
the bytes themselves are two length bytes If the number of content bytes is 
BYTECOUNT, then the first byte is defined as BYTECOUNT DIV 7, and the second 
byte is defined as BYTECOUNT MOD 7. In other words, the first byte specifics the 
number of groups of 7 bytes of content, and the second is the remainder. Note that the 
second byte will never have a value greater than 6. Both these bytes have their mosj 
significant bit set. 

The general overhead bytes are packet begin and end marks, sync bytes (6, to ensure 
correct synchronization of the IWMs), and a checksum. The checksum is computed by 
exclusive ORing all the content data bytes (8 bits) and the IDs, type bytes, status bytes, 
and length bytes. The checksum is 8 bits sent as 16. 

Figure 7-13 demonstrates the sequence of signal transitions that define the protocol 
for executing a read from a device. The signal transition points are described below. 

1. Host asserts REQ when ACK is negated-, command packet is coming from host 

2. Host enables IWM and sends packet to device. 

3. Device deasserts ACK, signaling host that packet was received. 

4 . \ lost responds by deasserfjng REQ, 

5. Device asserts ACK when it is ready to send response packet to host. 

6. Host asserts REQ when it is ready to receive response packet from device. 

7. Device enables IWM and sends response packet to host. 

8. Device deasserts ACK at end of packet. 

9. Host deasserts REQ when packet is received. 

10. Device asserts ACK to indicate it is ready to receive a command. 
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REQ 



ACK 



Drive iWM 



host IWM 



Oftve data 



Host data 




** 



^ 




Figure 7-13 

SmartPort bus communications: read protocol 

Figure 7-14 demonstrates the sequence of signal transitions that define the protocol 
for executing a write to a device. The signal uaasiiion points are described below. 

1. Host asserts REQ when ACK is negated and command packet is coming from host. 

2. Command packet is sent, 

3. Device asserts ACK, signaling it received the packet. 

4. Hosi negates ACK, finishing the command handshake. 

5. When REQ is negated and device is ready to receive daia, device negates ACK. 

6. When ACK is negated and host is ready to send, host asserts REQ. 

7. Hosi sends write data. 

8. Device asserts ACK, signaling it received the REQ. 

9. Host negates REQ, allowing device to write data to its media. 
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1 0. Device negates ACK and writes data to its media. 

1 1 , Host responds to negated ACK by asserting REQ, signaling it is ready for status, 
12 r Device responds to REQ by sending status to host 

13. Device asserts ACK, signaling status has been sent. 

14. Host acknowledges receipt of status by negating REQ. 

1 5. Device negates ACK when it is ready for the next command. 



REQ 



ACK 




^^ 




Drive IWM 



Host IWM 




Dnve data 




Host data 




Flgum 7-14 

Smart Port bus communications: write protocol 

Figure 7-15 illustrates that a command packet contains as few as zero and as many as 
767 data byteSi Each packet of 7 data bytes is encoded in a specific manner, described 
below, to assure that each data byte that is part of the packet has its most significant bit 
set- To allow all possible bit combinations to be transmitted in this manner, it is 
necessary to transmit 8 data bytes of encoded information for every 7 bytes of data. IT 
there is not an even multiple of 7 bytes in the total data block to be sent, then the 
remaining to 6 data bytes are encoded and sent preceding the packets of 7 encoded 
bytes, as 2 to 7 data bytes as described below. 
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SC3 



Packet begin matk 



Destination ID (SBQ-SFE) 



Source ID ($80-$ FE) 



host ID always = $80, 
5— first device In chain = S81, 
second aevlce In chain = $82 



Packet type ($80 -Command packet) 
C$81 -Status packet) 
($82- Data packet) 



Auk type C$80) 



Data status byte {7 bits) c$8Q-$FF) 



Length of packet contents "odd" bytes ($80-$86) 



Length of packet contents groups of 7 data bytes (S8Q-SED) 




c7 1 c5 1 c3 l el 



Packet contents 



Groups of 7 data bytes written as 8; 
most significant bits all In first byte 



Checksum (8-blt XOR of packet data 
and bytes 1-8 above) sent FM; 
every other bit = 1 



SC8 



Packet end mark 



Figure 7-15 

Smar+Porf bus packet format 



For each group of 7 data bytes in the block to be sent, take the bits of which those bytes 
arc composed and rearrange ibem as shown in Figure 7-l6. This changes the 7 bytes of 
input data into 8 byles of encoded data, in which each output data byte has its most 
significant bit set. 



J Odd group of 
0-6 oora bytes 
(2-7 bytes sent) 



Group of 
1 data bytes 
CS bytes sent) 



.n of 
7 da Fa bytes 
(B bytes sent) 



■ • » 



Group of 
7 data bytes 
(8 bytes sent; 



Packet su:es range from to 767 data bytes. 



Figure 7-16 

Smart/Port bus packet contents 

As Table 7-7 shows, the first byte contains the most significant bit of each of the 7 data 
bytes, the second byte contains the seven least significant bits of the first daia byte, the 
third byte contains the seven least significant bits of die third data byte, and so on for a 
total of 8 bytes of encoded data. This data is transmitted with the byte containing the 
most significant bits first, followed by each of the other 7 encoded data bytes in turn. 
Thus, you can see that if there are fewer than 7 data bytes tn an odd group, fewer than 8 
bytes of encoded data will be required to transmit this odd group. 
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Data byte encoding table 




Fop bits byte 


dl 7 


d2 7 


<&7 


Byte 1 


di s 


dl 5 


dl„ 


Byte 2 


d2 s 


d2 5 


d2 4 


Byle 3 


d\ 


d3 5 


d3 4 


Byte 4 


d4g 


d4 5 


d4 4 


Byte 5 


d5fi 


d5 5 


d5 A 


Byle 6 


d6 s 


Jo, 


d6 A 


Byle 7 


^6 


d7 s 


&4 



d4 7 
dl 3 
d2 3 
d3. 
d4 3 
d5 3 
d6 3 
d7, 



d5 7 


d6 7 


d7 7 


dl 2 


dl, 


dl n 


d2 2 


d2, 


d2 o 


d3 2 


dSt 


d3 


d4 2 


d4j 


d4 n 


d5 2 


^i 


d5 n 


d6 7 


d6. 


d6n 



d7. 



d7, 



d7n 



The number of bytes in the odd group is the remainder of the number of data bytes in 
the packet divided by 7. When encoding the odd byles, assume that die rest of the data 
bytes making up a group of 7 bytes ali contain zeros. Also note that if there are no odd 
bytes (that is, if the packet size divides by 7 evenly with no remainder), the odd-bytes 
group is simply omitted, Similarly, if the number of bytes in the packet is less than 7, 
there will be no encoded packets of 7 bytes, but only an odd-bytes group will be seni. 
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For example, if you are sending a 512-byte packet, the number of groups or 7 bytes is 
73, with a remainder or 1, Therefore, the first data byte will be sent as an odd group, 
followed by 73 groups of7 bytes each. The gioups of? bytes wil' lv . .nrodcd as 
indicated above and the odd bytes (byte number 1 of the packet, data bits 7..0) will be 
sent as shown in Figure 7-17. 



d W.O d2 Mi7..0 ^bttlJO Cj4 btt»7 *»70 d6 bit* 7 d? blti 7.0 



1 


01 ; 




















1 


a' a 




ai* 


d ' 3 


di j 


01, 


dl 



Figure 7-17 

Sir layout of a 7-byl© data packet 



Top bits oyre 



Figure 7- IS 

Iransrnltring a 1-byte data packet 

Note that the top bits for data bytes 2 through 7 in this example are set to zero, and the 
data bytes that would have contained the least significant data bits of bytes 2 Lhrough 7 
are not iransmiued. This is simply a special case of an instance of a group of 7 bytes. 

Tables 7-8 and 7-9 provide a visual summary of the contents of the standaid and 
extended command packets. Where there is an asterisk in the table, the value of the 
corresponding byte position is undefined and should be ignored by the device, 
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Table 7-8 

Standard command packet contents 



r 



Byte 


Status 


ReadBlock 


Writ© Block 


Format 


Control 


Intt 


Open 


Close 


Read 


Write 


1 


soo 


SOI 


$02 


$03 


$04 


S05 


$06 


$07 


508 


$09 


2 


Pa.ra.rn 
court 


Param 
counl 


Param 
count 


Param 
eoum 


Param 

count 


Param 
count 


Param 

count 


i'ar.-irr 
count 


Param 
count 


Param 
count 


< 


Byte 3 
of 

pa ram 
list 


Byie 3 
of 
par am 

list 


Byte 3 
of 

p;liani 
list 


* 


Byte 3 

of 

list 


■ 


Byie 3 

of 

| -jar am 
J Lsi 


Byte 3 
of 

param 
list 


Byte 3 

of 
param 

Jisi 


Byte 3 
of 

param 
list 


A 


Byie 4 
of 

1 X i r. ■- rr, 
list 


Byie 4 
of 

param 
List 


Byte 4 

of 

param 

lis) 


■ 


Byte 4 

of 
param 

list 


■ 


Byte- i 
Of 

pa i am 
list 


Byte 4 
of 

param 
list 


Byte 4 
of 

| XI :. jin 
List 


Byte 4 
of 

param 
list 


5 


» 


Byte 5 
of 

param 
list 


Byie 5 

Ml 

param 
list 


■ 




* 






Byte 5 

of 

param 

list 


Bvxe 5 
of 

param 
list 


6 


• 


Byie 6 
of 

param 
list 


Byte 6 
of 

param 
list 


• 




■ 


• 


• 


BVTX- - 

of 

p.ir rn 

list 


Byte 6 

of 

param 

lisi 


7 


■ 


Byie 7 
of 

param 
list 


Byie 7 
of 

param 
list 


♦ 




* 


► 


• 


Bvte 7 
of 

param 
list 


Byte 7 
of 

param 

list 


s 


* 


* 


- 


* 


* 


• 


« 




Byte 8 
of 

param 

list 


Byte 8 
of 

param 
list 


' 


■ 


1 


* 


4 


# 


i 


• 




Byte 9 

of 

param 

list 


Byte 9 
of 

param 
list 



* A byte with an indeterminate value; the device should ignore the byte. 
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Tobl* 7-9 

Extended cor 


nmand packet contents 
Read Block WritsBloek Format 


Control 














lyle Status 


init 


Open 


Close 


Read 


Writ* 




1 $40 


$41 


$42 £43 


S44 


S45 


S46 


S47 


S48 


S49 




2 Param 

court 


Param 

count 


Param Param 
count court 


Param 
count 


Para i i 
count 


Param 
count 


Param 
count 


Param 
count 


Patau: 
count 




3 Byte 5 
of 


Byte 5 
of 


Byte 5 

of 


Byte 5 

of 


■ 


Byte 5 
of 


Byte 5 
of 


Byte 5 
of 


Byie 5 
of 




pawn 
list 


param 
list 


param 
list 


param 
list 




param 

list 


param 
list 


param 


param 

list 




4 Byte 6 

oi 


Byie 6 

of 


Byte 6 
of 


Byte 6 
of 


* 


Byte 6 
of 


Byte 6 
of 


Byte 6 
of 


Bvtc 6 

i 




parain 
list 


param 
list 


param 
list 


pawn 

list 




param 
List 


param 
list 


pararn 

list 


param 

List 




5 


Byte 7 
of 

param 
list 


Byte 7 
of 

param 

list 


* 


* 


■ 


■ 


Byte 7 

or 

param 
list 


Byte 7 
of 

param 
list 




1 6 


Byte 8 

of 

param 

list 


Byte 8 
oF 

param 
list 


■ 


■ 


■ 


• 


Byte 8 
of 

param 
list 


Byte 8 
Of 

param 
list 




1 7 


Byte 9 

of 

param 

list 


Byie 9 
of 

param 
list 


* 


■ 


■ 


* 


Byte 9 
of 

param 
list 


Byte 9 

of 

param 
list 




6 


■ 


• • 


■ 


m 


• 




Byte 10 

of 
param 

llM 


Byte 10 

or 

param 
list 




| 9 


* 


■ * 


- 


m 


- 




Byte 11 

or 


Byte 11 
Of 
















param 
list 


paiarn 
list 




; " A byie with an indeterminate value; the device should ignore 


the byle. 
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This chapier describes how [he Apple IIGS handles interrupts from the available 
interrupt sources. You can find additional information about interrupts in 

•endix D, "Vectors ." This chapter describes interrupts in general and the 
Apple IIGS built-in interrupi-handler firmware in particular and how to manage 
environment variables during interrupt handling, It also summarizes all interrupt 
sources, discussing how often each source interrupts the system and the relative 
priority assigned by die system to each source, and provides some details about Break 
instructions, the ApplcMouse™, and serial-port interrupt handling. 

As a user's program runs, it may get interrupted by various sources to process 
important external inputs. The system assigns priorities to each of these interrupt 
sources and handles them in a defined .sequence. When the user's program is 
Interrupted, the state of the system at the lime of the interrupt is saved. On completion 
of interrupt processing, the program can continue as though nothing had happened. 

There are many reasons for the system to interrupt the execution of a program For 
example, if the user moves the mouse, I he system should read the mouse location to 
keep the pointer location current If the system handles the interrupt promptly, the 
mouse pointer's movement on the screen will be smooth instead of jerky and uneven. 
Or your program may be performing another operation while characters are being 
received in a serial input buffer, and you do not want to lose any characters from the 
input stream. These conditions, and many others, can cause your program to be 
interrupted to handle an error or some other special condition dial requires 
immediate attention. 

The Apple IIGS interrupt-handler firmware supports interrupts in any memory 
configuration. To do this, the system saves the machine's state at the lime of the 
interrupt, placing the Apple TIGS in a standard memory configuration before calling 
your program's interrupt handler, and then restores the original state when your 
program's interrupt handler is finished. 

If you write your own interrupt- processing routines, you can allach them to the system 
by modifying the interrupt vector locations specified in Appendix D, "Vectors ." 
! lowever, you must obey all of the conventions specified in this chapter regarding 
interrupt processing and make sure Co restore the environment lo the state in which 
you found it on entry to your interrupt-processing routine. This will allow the system to 
restore the environment to its original state. 
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What is an interrupt? 

An interrupt is most often caused by an externa] signal that tells the computer to stop 
what it is currently doing and devote its attention to a more important task. Besides 
this external hardware- related signal, software interrupts are possible as well. 

Hardware interrupt priorities are established through a daisy-chain arrangement using 
two pins, INT IN and INT OUT, on each peripheral-card slot. Each peripheral card 
breaks the chain when it issues an interrupt request. On peripheral cards that don'i 
interrupts, the designer of the peripheral card should connect these pins to one 
another, thereby passing the interrupt signal directly through the card slot. 

Wfcefi trl6 Merrupt: RgqUeSI (IRQ) Unt 5R trie Apple IJC§ microprocessor is ScfiV 
or when a software interrupt occurs, the microprocessor transfers control to the 
imerrupt-processing routines by jumping through vectors stored in ROM The built-in 
interrupt handler processes the interrupt if the application has not provided its own 
interrupt handler. 



What is art Interrupt? 
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The built-in interrupt handler 

The Apple IIGS built-in imerrupi handler performs a sequence of steps to handle 
system interrupts. Figure 8-1 shows the structure of the built-in interrupt handler. 



EABOR 



65C816 
inteirupf 
vectors 
[Bank Sf r .: 




Sot flags 10 
Idenf-fy source 



IRQ 



CCP 



SCD7I-SC07F 

Abort 



Bonk SE1 

vector 










Si 




T 


Bonn SE f 






/ 


vector 




Simulate 
a Brsak 


J 






— / 


BonkSfl 

ktaftnr 







Enter 
Monitor 



JSl Aopie?a'k 
JSL serial Interrupt 



ves 



JSL SrcXX ■#- 

JSL Srcvy •+ 

JSL SrcZZ (and so on) ^- 

JSL other ^h 



Po i all 

o'hsr 

■ourcm 



T 



<S3FE) 
Bank 500 



No 





Ves 



Break handler 




Save 

some state 
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Switch 
to 

niQh 
speed 



NO 



Restore 

state 



<S3F0) 
Bank $00 



I 



Exit 
Interrupt 



Figure 6-1 

Built-in Interrupt handler 
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IT I/O shadowing is on, then the system ROM in bank $FF is shadowed (and readable) 
in bank $O0. The system jumps indirectly through the interrupt vector located either at 
EIRQ (SFFFE, SFFFF) if it was running in emulation mode when the interrupt occurred 
or at NIRQ ($FFE4, $FFE5) if iL was running in native mode. 



Important 

If I/O shadowing Is off, RAM will b© addressed In the memory space of bank SOO In 
the area of SFFEO-SFFFF, the location at which the Interrupt vectors are stored. 
When an Interrupt occurs, the 65C816 uses the Interrupt vector located In the 
RAM vector table If I/O shadowing Is off and uses the vector located In the ROM 
vector table if I/O shadowing is on. If you have not correctly set up the RAM 
vectors and you turn off I/O shadowing, the system will foil. 



Both EIRQ and NIRQ jump to ROM located within the soft-switch area at 
SO071-SC07F. This special ROM code sets status flags that identify die type of interrupt 
that has just occurred. 

■\i this point, the system tests to see whether the interrupt was a result of a software 
Break instruction. If it was, Lhe system vectors to the break handler (normally the 
system Monitor) through the user interrupt-handler vector in bank SET An 
application will patch this vector only if it wants to be responsible for handling or to be 
informed about all interrupts that occur. If the application simply wants information, 
it must save the vector value that the application finds in this location and then jump 
through this vector as the user-interrupt code is completed. Saving and using the 
vector allows the system to proceed as though Lhe application had never gotten in the 
way in the first place. If the application wants to handle all interrupt processing on its 
own, it must be responsible for restoring any environment variables that it changes 
and must execute an RTl instruction directly from its own code, returning to the 
application that was interrupted. 

If the interrupt source was not a Break instruction, the interrupt handler saves the 
absolute minimum amount of information about the machine slate. The interrupt 
source might have been AppleTalk (tested first) or the serial port (tested next)- If you 
are running at high baud rates and if interrupt processing takes too long, you might 
begin to miss characters. To save the minimum machine stale, save only the 
environment variables that have to be used in the routine that saves an incoming serial 
character in a buffer and points the buffer pointer to its next location. To see whether 
the interrupt was from a serial port, the 5CC is tested. If it is a serial interrupt, the 
firmware performs a JSL inslruetion through a patch address in bank SE1 to the port 
handler (see Appendix D, "Vectors," for more information). 
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if the port handler returns with the carry bil set, the system does not have an internal 
serial-port handler installed. The interrupt handler now proceeds 10 save the rest of 
the machine state and establish a specific interrupt memory configuration as 
described in the section "Saving the Current Environment" later in this chapter. (You 
musl poll each of the possible interrupt sources to determine which requires service.) 

A3 ibis point, die interrupt system begins a polling loop, testing each of the possible 
interrupt sources in turn. If no internal interrupt handler \& installed, then (and only 
ihen) [he firmware jumps through the user interrupt vector routine to handle the 
inierrupt. The address of the user interrupt routine is found in bank S00, addresses 
i (low byic) and S3FF (high byte) 

The S3FE interrupt handler (user interrupt vector routine) must do the following; 
verily that the interrupt tame from the expected source 

r handle ihe interrupt appropriately 

□ clear the appropriate interrupt soft switch 

□ restore everything to the state it was in when the Inierrupt Request routine was 
entered, if your routine has made any changes to the state of the machine 

□ return to the built-in interrupt handler by executing an RT1 instruction 

After the user inierrupt vector routine completes its action, the built-in interrupt 
handler restores the memory configuration and then executes another RTI to return to 
where it was when the interrupt occurred. 

Here are some factors to remember when you are dealing with programs that run m an 
interrupt environment: 

□ There is no guaranteed maximum response time for interrupts because the system 
may be performing a disk operation that lasts for several seconds w r hen the interrupt 
occurs. 

n Interrupt overhead will be greater if your interrupt handler is installed through an 
operating system's inierrupt dispatcher. The length of delay depends on the 
operating system and on wliether the operating system dispatches the interrupt to 
other routines before calling yours. 
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Summary of system interrupts 




Table 8-1 lists the 


source and type o 


f each interrupt and describes each one. 






Table 8-1 

Summary of system interrupts 






Interrupt source 


Type 


Description 


Power up 


RESET 


Generated by powering up Apple IIGS. 




Reset key 


RESET 


Generated by the ADB microcontroller when 
Control-Reset is pressed. 






External card! 


RESET 


Available. 






External card 


NM1 


Used only for debugging. 






Abort signal 


ABORT 


Activated by memory card slot. 






COP instruction 


COP/native 


In native mode, the user executed a COP 
instruction. 






COP 


GOP/emulation 


In emulation mode, the user executed a COP 
instruction; 






Break instruction 


BRK/native 


In native mode, the user executed a Break 
(BRK) instruction. 






Break 


BRK/emulation 


In emulation mode, the user executed a Break 
(BRK) instruction. 






AppleTalk 


IRQ 


Interrupts upon address recognition or an 
error. 






Serial input *1 
(SCC channel A) 


IRQ 


Interrupts when transmitter is empty, 
transmission is received, or an error 
occurs. 






Serial input *2 
(SCC channel B) 


IRQ 


Same as serial input #1. 






Scan line 


IRQ 


Interrupts at end of requested scan lines, 










(continued) 
Summary of system Interrupts 
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Table 3-1 

Summary of system Interrupts (continued) 



Interrupt source type 



Description 



Ensoniq chip 



VBL signal 



Mouse 



Keyboard 
Response 



SRQ 



Clock chip 

Internal card 
EXTINT 



IKQ 



IRQ 



IRQ 



Quarter-second IRQ 

timer 



IRQ 
IRQ 



IRQ 



Desk Manager IRQ 

Flush command IRQ 
Micro abort IRQ 



IRQ 

IRQ 
IRQ 



Interrupts when an oscillator completes a 
waveform table (32 possible in term pis from 
here), 

Interrupts when vertical blanking (VBL) is 
requested, 

Interrupts as requested at mouse button press 
or movement or at a VBL signal. 

Interrupts system every 0.26667 second for 
AppIeTalk use. 

Interrupts upon keypress. 

Generated when data is ready for the system 
from the Apple DeskTop Bus (ADB) 
microcontroller; initiated as a result of a 
system generated command- 
Generated when an ADB device requires 
servicing. 

Generated by the ADB microcontroller when 
Control-d-Esc is pressed- 

(3-Control Delete was pressed. 

Generated if the ADB microcontroller detects 
a fatal error within itself. 

A 1 -second timer interrupt is generated by 
the l-hcrtz, signal from the clock chip through 
the VGC chip. 

The card wants the attention of the 65G816. 

Available from the VGC, but not to hook an 
external interrupting device-, hardware is run 
available. 
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Interrupt vectors 






Table 8-1 described the 


sources of interrupt and named the interrupt vector that 


contains the address of the routine tha 


t processes each interrupt- Table 8-2 defines die 


locations at which each of the named 


interrupt vectors resides. 


Table 8-2 






Interrupt vectors 






Address 


Name 


Description 


$FFFE-5FFFF 


IRQVECT 


Emulation-mode IRQ/BRK vector 


SFFFC-SFFFD 


RESET 


Emulation- or native -mode RESET vector 


4FFFA-SFFFB 


NMI 


Emulation- mode NMI vector 


$FFFB-$FFF9 


EABORT 


Emulation-mode ABORT vector 


SFFF4-SFFF5 


ECOP 


Emulation-mode COP vector 


$FFEE-$FFEF 


NIRQ 


Native-mode IRQ vector 


$FFEA-$FFEB 


NNMI 


Native-mode NMI vector 


$FFE8-SFFE9 


NABORT 


Native-mode ABORT vector 


$FFE6-SFFE7 


N BREAK 


Native-mode BRK vector 


4FFE4-4FFE5 


NCOP 


Native-mode COP vector 



If I/O shadowing Ls on, the vectors contained in ROM are always used by the 65C816, 
regardless of the language-card settings. This allows you to run native-mode code with 
interrupts enabled in old applications. 

If the application program or operating system disables I/O shadowing in bank S00 or 
401. then cither live application program or the operating system must copy the ROM 
vectors from $FFEE to SFFFF and the code from $C071 to SC07F into RAM at the same 
locations before enabling interrupts. If the code is not copied from ROM to RAM, the 
Monitor's interrupt code cannot be used 



Interrupt priorities 

The 65CB16 processes each type of interrupt on a priority basis. For instance, if several 
of the many IRQ interrupts should occur at the same time, the 65C816 will process all 
AppleTalk IRQs before any keyboard interrupts. Priorities for each type of interrupt 
aie indicated by their relative position in the following paragraphs. In other words, 
the highest-priority interrupts appear closest to the beginning of these descriptions. 
Lower-priori ry interrupts appear later in the descriptions. 
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RESET 

RESET forces emulation mode. The interrupt is processed by the firmware and then 
vectors to the user link. A cold start attempts to boot a disk. A cold start can be 
performed in two ways: 

r by turning the power off and on 

D by pressing O-Control-Reset 

RESET oold-siart functions are as follows: 

D sets up video 

d sets video as output device 

□ seis keyboard as input device 

D reads clock chip and places system configuration in firmware RAM 

□ sets up system to match configuration in firmware RAM 

D sets up the power-up byte so the next RESET performs a warm start 

D scans slots for Disk 11 devices and sets motor-on detect bit (motor-on detect causes 
the FPI chip to slow the system down to 1 MHz when the moior-on soft switch is 
enabled, and it restores the system speed when the motor is turned off) 

d goes to, or scans, for boot device (if boot device is found, lumps to it; if no boot 
device is detected, switches in Applesoft BASIC and jumps to it) 

A warm start vectors to user links. If user did not alter links, then a BASIC cold start is 
executed. A warm start can be performed in two ways: 

□ by pressing Control- Reset 

□ by using peripheral cards (pulling RESET line low) 

The system executes the following reset warm-start functions: 

D sets up video 

D sets video as output device 

□ sets keyboard as input device 

d reads image of system configuration in firmware RAM 

D sets up system to match configuration 

□ generates tone (beep replaaid with tone) 
d jumps to user reset vector 

NMI 

NMI vectors to user link. No NMI interrupts are used by the Monitor. Peripheral cards 
pull NMI line low. 
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ABORT 

ABORT vectors to the user link. If no user link exists, it vectors to the break handler that 
displays the address and opcode of the code being executed at ihe lime ihe abort pin 
un ilic 65C816 was pulled low (see BRK). The ABORT interrupt can be activated only 
by hardware installed in the memory-expansion slot, 

COP 

COP vectors to the COP (coprocessor opcode) manager vector in RAM, which points 
Id ihe firmware. If ihe COP manager is not installed, the firmware displays Lhe COP 
message via a software COP instruction. 

In emulation mode. COP prints the following: 

Ibbfaddr: 00 cc COP cc 

fc*aaaa 5C~xxxx Y-yyyy S-ssas D-dddd P-pp 
B-bb K-klc M-mm Q-qq L-l m-rn x-x o»l 

In native mode, COP prints the following: 

bb/addr: 00 cc COP cc 

h-aaaa X-xxxx Y-yyyy S-ssss D-dddd P^pp 

B"bb K=kic M=fitm Q=qq L=l m=ni x=x e=0 

♦ Note: The preceding formats arc for a 40-column screen. On an B0-column screen, 
the second two lines become one line. The cc appearing in both modes is the 
operand of the COP instruction and indicates lo the user where lhe COP occurred 
($00 through $FF are valid COP operands). 



BRK 

In emulation mode, the interrupt vectors to the interrupt (!RQ) handler and then to 
the break handler. In native mode, the interrupt vectors directly to a break handler. 
This occurs via a software BRK instruction only. The break handler saves as much data 
as the interrupt handler. This allows you to invoke the Monitor Resume command (H) 
to continue program execution. 

In emulation mode,, the Break instruction prints the following: 

bb/addrj 03 be BWK cc 

A=aaaa x-xxxx Y-yyyy 5-ssss D=dddd P^-pp 

B-bb K-kfc H=mffl Q=qq L=l m=rn x=x e= 1 

In native mode, the Break instruction prints the following: 

bb/addr: 00 be BRK cc 

A-aaaa X=xxxx Y=yyyy S=ss3s D=dddd 
B»bb K=kk K=nm 0=qq L=l m=m x=x 

* Note: The preceding formats are for a 40-column screen. On an 80-column screen, 
the second tw r o lines become one line, The cc appearing in both modes is the 
operand of trie BRK instruction and indicates to the user where the BRK occui 
C$00 through SFF are valid BRK operands). 
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IRQ 

IRQ intern.! pis are as follows: 

AppleTalk: I his interrupt has the highest priority because its code is very time 
intensive; data can be lost if the SCC is not read within 104.167 microseconds 
(baud = 230,400) after an AppleTalk SCC interrupt occurs. 

Serial ports: In interrupt mode, data will be lost if the SCC is not read within 1 
milliseconds Cbaud = 19,200) after the interrupt occurs. 

Scan line: The scan-line interrupt can occur every 63.694 microseconds, When the 
video counters count down to zero, the interrupt occurs, The video counters reach 
zero when the scanning beam reaches the right side of the scan line. 

Ensonlq chip: The Ensoniq chip interrupts when the wavchirni buffer is completed. 
Because the chip contains 32 oscillators , there are 32 possible interrupts from the 
chip. 

VBL: The VBL interrupts every 16.6667 milliseconds. The interrupt occurs when the 
scanning beam is retracing from the bottom-right corner to the upper-left corner of 
the screen. {Note: Using the heartbeat interrupt handler is the approved method of 
executing VBL interrupt tasks.) 

Mouse: The mouse interrupts only if the interrupt option is specified, The interrupt 
options are mouse movement, mouse button press, and VBL signal 

Quarter-second timer: Tins timer interrupts every 0.26667 second. The timer is used 
by AppleTalk to trigger event processing. 

Keyboard: The keyboard interrupts if a key is pressed. 

Response: If a command is sent to the ADB microcontroller, the interrupt occurs 
when the "done" flag is set. The microcontroller interrupts the system when the 
response data is ready for the system to read. If this interrupt occurs, control is passed 
to the response manager. 

SRQ: If an ADB device requires servicing, an SRQ (service request) is issued, This 
event can interrupt the system. When this interrupt occurs, control is passed to the 
SRQ manager. 

Desk Manager: The ADB microcontroller causes this interrupt if Conirol-C^Rsc is 
pressed. Control is then passed to the Desk Manager. 

Flush: If ti-Control-Backspace (Delete) is pressed, the ADB microcontroller clears its 
internal type-ahead buffer, issues a Flush command to external keyboards, and causes 
an interrupt. If this interrupt occurs, control is passed to the Scrap Manager. 

Micro abort: If the ADB microcontroller detects a fatal error and the fatal-error 
interrupt occurs, the system is interrupted. If this interrupt occurs, control is passed to 
the ADB Tool Set. 

Clock chip: The clock chip interrupts once each second. 

External cards: External cards cause interrupts as defined by the card manufacturer. 
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Environment handling for interrupt processing 

For each interrupt discussed in the previous section, the processor can be in either 
emulation or native mode. Each mode has its own interrupt vector-, therefore, there 
are two different entry points to the interrupt handler. To process interrupts correctly, 
the system interrupt handler must save the current environment, set the interrupt 
environment, and process the interrupt through the appropriate interrupt handler. 
(You can find more information about saving and restoring the environment m 
Chapter 2, "Notes for Programmers." Thai chapter contains sample assembly- 
language code that saves a part of your environment and sets the system into the 
correct mode for interrupt processing.) 



Saving the current environment 

On entry to each interrupt, the system interrupt handler saves die current 
environment and sets the program bank, data bank, and direct-page register contents 
to zero. 

The slate of the machine upon entry into each interrupt handler is indicated by the 
amiL-iiLs i : i i ] 1 1 ■ Following registers: 

D program bank 

D data bank 

D direct register 

Q processor status 

D A register 

d X register 

D Y register 

The RAM or ROM state, including emulation or native mode, is indicated by the 
following: 

D language-card stale (bank 1 or 2, ROM or RAM) 

□ main or alternate memory (and main and alternate zero page) 



JRE switch 
)bl ORE switch 



D 40- or ftO-column video 
d main stack or zero page in use 
□ speed register 
D Shadow register 
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Going to the interrupt environment 

If the interrupl can be processed by the firmware or a tool set, the processor vectors to 
the appropriate handler in native mode, 8- bit m/x, in high speed. IF the interrupt 
cannot be processed by the firmware, the processor performs Ihe following steps: 

1 . Switches io emulation mode 

2. Switches speed to I MHz 

3 . Switches in text page 1 to make main screen holes available 

4. Switches in main memory For reading and wriling 

5. Maps SDOOQ-SFFFF ROM into bank $00 

6. Switches in main slack and zero page 

7. Saves the auxiliary stack pointer and restores the main slack pointer 

After the environment is saved and the new environment is set, the interrupt handler 
checks for the source of the interrupl. If die interrupt is a firmware interrupt only (a 
BRK or COP instruction), the firmware jumps (using a JSL) to the appropriate firmware 
routine. If ii is an interrupt thai is passed directly io the user, then the firmware passes 
ihe interrupt to the user via the appropriate links. An interrupl can be both processed 
by the firmware and passed to the user. If both occur, the preceding rules listed still 
hold, except that the particular firmware interrupl handler will return 10 the main 
interrupt handler with carry set (C - 1) instead of clear CC - 0), which indicates that the 
firmware processed the interrupt and the user does not need to know aboul it. 






Restoring the original environment 

After ihe interrupt has been processed, the system interrupt handler restores the 
environment and registers to their preinterrupt state and performs an RTl, reluming to 
executing program. 

♦ Note.- The peripheral card (or equivalent internal card) in use is responsible for 
saving its slot number in the form SCn (n = slot number) at MSLOT ($0007F8), 
MSLOT is used in the Interrupt handler to reslore the currently executing slot 
number's SC800 space after an interrupt has txnen processed. 

Emulation-mode interrupts are supported in bank $00 only, Naiive-modc 
interrupts are supported everywhere in memory. Therefore, code running 
anywhere except in bank $00 must be native-mode CQi k 
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Handling Break instructions 

In emulation mode, the Apple IIGS detects a software Break (BRK) instruction as an 
IRQ and jumps through the emulation-mode IRQ vector. In that code, the firmware 
determines that a Break instruction was issued and so jumps through the emulation- 
mode BRK vector. In native mode, the 65C816 can tell the difference between BRK 
and IRQ, so it jumps directly through the native-mode BRK vector. 



Apple IIGS mouse interrupts 

The Apple DeskTop Bus (ADB) microcontroller periodically polls the ADB mouse to 
check for activity. If the mouse has moved or the mouse button has been pushed, the 
mouse firmware wilt respond to the microcontroller by returning 2 byles of data. The 
microcontroller returns this data to the system by writing both mouse data bytes 10 the 
GLU chip (mouse byte Y followed by byte X — this enables the interrupt), Data bytes 
are read only if the Event Manager (if active) or the application program issues the 
mouse firmware call or the tool call ReadMouse. The GLU chip is the general logic unit 
that provides logic elements enabling the 65C816 to communicate with the ADB 
microcontroller. 

The Apple IIGS mouse firmware causes interrupts for the 65C816 microprocessor only 
if the interrupt mode has been selected via firmware. The Apple IIGS mouse interrupts 
in synchronization with the Apple IIGS vertical blanking signal (VBL). The mouse can 
interrupt the 65C8I6 a maximum of 60 times per second. This cuts down on the burden 
the mouse puts on the 65C816. 

At power-up or reset, the GLU chip turns the mouse interrupt off and enters the mouse 
into a noninterrupt state. 



Serial- port interrupt notification 

When a channel has buffering enabled, the firmware services all interrupts that occur 
on that channel. If an application wishes to service interrupts for a given channel 
itself, the application should disable buffering using the BD command in the output 
flow, If the buffering mode is off, the serial-port firmware will not process any 
interrupts. The system interrupt handler will transfer control to the user's interrupt 
vector as S03FE in bank 500 (this is the ProDOS user interrupt vector}. The user's 
interrupt service handler is then completely responsible for all serial-port interrupt 
service. You can find further details about the serial-port firmware and its commands 
in Chapter 5, "Serial-Port Firmware." 
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If the application does not want to disable buffering, but does wish to be notified thai a 
certain type of serial-port interrupt has occurred, the application can instruct the 
firmware to pass control to an application-installed routine after the system has 
serviced the interrupt. The application tells the firmware when it wishes to be notified 
and establishes the address of the application's completion routine by using the 
Sellntlnfo routine. This call guarantees that the completion routine will get control 
when a specific type of interrupt occurs, but only after the serial-port firmware has 
processed and cleared the interrupt. The application Lhen uses the GetlnUnfo routine 
to determine 'which interrupt condition occurred. 

A terminal emulator offers a typical example of when interrupt notification might be 
desirable. The emulator usually should perform input and output character buffering, 
handshaking, and other such operations. The terminal emulator can be designed to 
allow the firmware to handle all character- buffering details. The designer of the 
emulator can have the firmware signal this emulator program when the firmware 
receives a break character. To enable this special-condition notification, the emulator 
application sets the break interrupt enable function by using the Setlntlnfo routine. 
When the firmware receives a break character, the firmware SCC internjpi handler 
then records and clears the interrupt and finally passes control to the emulator's 
completion routine. This routine calls Getlntlnfo, and if the break bit is set, the 
completion routine knows lhal a break character has been received. 

Note that all interrupt sources (except receive and transmit) cause an interrupt on a 
transition in a given signal. This means that the user's interrupt handler will get 
control passed lo il on both positive and negative transitions in the signals of interest. 
For example, a break-character sequence causes two interrupts: one at the beginning 
of the sequence and one at the end, The user's interrupt handler should take this into 
account A routine can always determine the current stale of the bits of interest by 
using die GeiPonStat routine, 

The internjpi completion routine executes as part of the firmware interrupt handler 
and must run in that environment. In addition, the following environment variables 
must be preserved at their entry to your routine: 

DBR - $00. e-0, m-1, x-1 

Registers A, X, and Y need not be preserved. 
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This chapter describes the Apple DeskTop Bus (ADB) microcontroller. This hardware 
device collects information from the ADB peripheral devices. In association with the 
ADB Tool Set, the data that is collected is available to the user. Typical data includes 
key-down and key-up sequences , mouse moves, and button clacks. The firmware thai 
performs these operations is not documented here. See the ADB Tool Set 
documentation for information about the ADB firmware. This chapter is IVr reference 
only, providing a developer's view of the complete ADB system. 

The ADB device is an I/O port with its own microcontroller. The microcontroller 
accepts commands from the 65C816, manages the internal keyboard, and acts as a 
host processor for ADB peripheral devices such as the mouse, the detachable 
keyboard, and other devices that follow the ADB protocol. 

The ADB system has four components and three distinct software interfaces. 
Figure 9-1 shows the ADB system from a hardware perspective. 






6SC816 
microprocessor 




A 3 3 



Mouse 



Keyboard 



Figure 9-1 

Apple DeskTop Bus components 

The four hardware components are the 65C816, the GLU (general logic unit) chip, the 
ADB microcontroller, and the components attached to the Apple DeskTop Bus 
device. The application accesses the ADB components through the ADB Tool Set. 
The ADB Tool Set talks to the hardware by sending commands through the d\ I l hip 
to the microcontroller. Some of these commands require data transfer over the ADB, 
and others terminate in the microcontroller. 

The GLU chip is actually a set of hardware registers (sometimes called mailbox 
registers) that the 65C816 uses to transmit commands and data to the microcontroller 
from the 65C816 and that the microcontroller uses to pass data to the 65C816. Both the 
65C816 and die microcontroller arc independent processors, each running at its own 
pace. They exchange data through the GLU chip. 

The microcontroller translates the commands it receives into data streams that it 
sends along the Apple DeskTop Bus device itself. All peripheral devices attached to 
the bus listen lo the data stream being transmitted. If the command is intended for a 
specific peripheral device, it responds and possibly transmits data and status 
information back to the microcontroller. The microcontroller, in turn, translates the 
data and sends the translated data to the 65C816. 
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There is actually one more software interface: the program running independently in 
the microcontroller itself. But that is immaterial here. It is sufficient to note thai this is 
an intelligent peripheral device that manages communication. 

The Apple IIGS Hardware Reference provides details about the hardware interface 
between the ADB microcontroller and its attached peripheral devices and how the 
microcontroller manages the internal and external keyboard and the mouse, the reset 
sequence and the d key, key buffering (type-ahead),, and so on. 

The Apple lies Toolbox Reference provides details about the high-level commands 
that allow access to the items attached to the ADB. 

Although most applications do not require the information in this chapter, there are a 
exceptions: 

□ applications that allow the user to temporarily change Control Panel options 

□ alternative input devices such as a graphics tablet (however, an application may noi 
need to worry about this because a device driver can be transparently hooked into 
the Event Manager) 

D multi player or multidevice applications 

If an application needs to temporarily change some Control Panel options, use the 
ADB Tool Set. Note, however, that changing certain options can cause the system to 
fail. 

An application should not call the ADB Tool Set to change Control Panel options 
permanently. If a permanent change in certain system characteristics, such as ihe 
auto-repeat rate or buffer-mode options, is necessary, the application should make 
the changes by changing the Battery RAM (using the Miscellaneous Tool Set). 1 
the application should call the routine TO BR AM SETUP to update the system wiLh the 
new Battery RAM values 

If you are writing a user program that uses the mouse and the keyboard, you will 
probably not need the information in the rest of this chapter. For that level of 
information, see the Apple IIGS Toolbox Reference. If you arc a hardware developer 
developing a new peripheral device for the Apple DeskTop Bus, you will need the 
information given here as well as the information about the bus protocol itself and 
interface specifications for ADB devices. This latter information is in the Apple TIGS 
Hardware Reference. 

The discussion in this chapter focuses on the ADB microcontroller and its 
commands. The rest of this chapter is for reference only; it shows the application 
designer the kinds of commands the ADB Tool Set issues to the microcontroller. You 
should not attempt to send any of these command streams to the microcontroller 
yourself. 

Important 

Microcontroller communication Is exclusively ttie Job of the Apple lies Tool Set. 
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ADB microcontroller commands 

The microcontroller uses two types of commands: default and mode commands and 
ADB commands. The default and mode commands are used by the Conirol Panel to 
change system sellings. The ADB commands are used to communicate with ADR 
devices other than the detachable keyboard and the mouse (these are handled 
automatically). 



Caution 

An application program must' Issue microcontroller commands only through the 
ADB Tool Set If you attempt to use these commands directly, bypassing the tool 
set. you could cause a system failure. (For more Information about the tool set. 
see the Apple llss Toolbox Reference.) 

This section provides a detailed description of each ADB microcontroller command. 
The command values are given in binary format where the most significant bit is the 
leftmost bit. A percent sign (%) preceding a string of zeroes and ones indicates a 
binary value. The notation xy subsli luted for a binary digit pair in a command byte 
siands for 2 bits lhai select one of four possible registers. The notation abed substituted 
far Tour binary digits in a command byte, stands for 4 bits that select one of 16 possible 
device addresses. The ADB can support up lo 16 different device addresses, each of 
which may have four hardware registers. 



Abort, $01 

This command synchjonizes the microcontroller with the 65C816 microprocessor 
when a command error occurs. Abort is a 1-byte command wilh a value of %0O00Q00T, 



Reset Keyboard Microcontroller $02 

This command returns the keyboard microcontroller to its power-up state. It is a 1- 
byte command with a value of %00000010. 



Flush Keyboard Buffer, $03 

This command clears the keyboard buffer. Any keystrokes that were pending are 
foremen. Il i;s a. J hvu: command Willi :.t value of W00000011, 
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Set Modes, $04 

This command sets modes. Ii is a 2-byte command; the first byte value is %0OOO0100. 
For each bit set in the byte lhai follows the Set Modes command, ihe corresponding 
mode bit is set. 



Clear Modes, $05 

This command clears modes. H is a 2-byte command; the first byte value is 
%00000'IQI. For each bit set in the byte that follows the Clear Modes command, the 
corresponding mode bit is cleared. 

Table 9-1 lists command bit functions 

Table 9-1 
Bit functions 



Sil 



Function 



Resets from the ADB detachable keyboard alone when the Reset key alone is 
pressed CControl not needed); works only with the detachable keyboard. 

6 Sets the exclusive-OR/Lock-Shift mode. (With the Caps lock key down, you type 

lowercase characters when you press the Shift key.) 

5 Reserved. 

1 Duffer keyboard mode. 

3 Enables 4X repeat instead of dual (230 repeat. CWhen the Control key is 

pressed, the repeat speed for arrows is four limes the normal speed.) 

2 Includes the Space bar and Delete key on dual repeat (When the Control key is 
pressed, the repeat speed for Space bar, Delete key, and arrows is doubled.) 

1 Disables ADB mouse autopoil (disables the mouse). 

Disables ADB keyboard autopoil (disables the keyboard), 
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Set Configuration Bytes, $06 

This command sets configuration bytes. This is a 4-byte command (%OOOO0ll0) thai 
uses the 3 bytes following the command as follows: 



Byte 


1 


High nibble 
Low nibble 


Byte 2 


High nibble 


Low nibhlr 


Byte 3 


I ligh nibble ! 



1 
2 

3 

■-I 


1/4 sec 
1/2 sec 
3/4 sec 
1 sec 
No repeat 


Low nibble J 


1 
2 

3 

:• 
6 

7 


40 keys/Sec 
30 keys/sec 
2'i keys/sec 
20 keys/sec 
15 keys/sec 
11 keys/sec 
8 keys/see 
A keys/sec 



ADB mouse address 
ADB keyboard address 



Sets character set (needed for certain languages) most significant bit if 
keypad V swapped with V 

SefS IcevhrrcrH IjvomI hnoi»ia«> faoo T«bla a_gft 



Sets delay to repeat rate (3 bits) 



Sets auto-repeat rate (3 bits) 



Table 9-2 lists the keyboard language codes used for byte 2 of the Set Configuration 
Bytes command. 

Table 9-2 

Keyboard language codes 



Language 


Abbreviation 


Code 


Language 


Abbreviation 


Code 


English (U.S.) 


US 





Italian 


IT 


5 


English (U.K.) 


UK 


1 


German 


GR 


|. 


French 


FR 


2 


Swedish 


SW 


7 


Danish 


DN 


3 


Dvorak 


DV 


8 


Spanish 


SP 


4 


Canadian 


CN 


C J 
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Sync, $07 

This command performs three of the preceding commands in sequence. It sets the 
mode byte (see "Set Modes, S04" and "Clear Modes, 505") followed by the Set 
Configuration Bytes (see "Set Configuration Bytes, $06"). This command is issued by 
the system after a reset operation. After receiving the command, the microcontroller 
resets itself to its internal power-up state and then resets all ADB devices. Sync is a 
1-byte command with a value of W00000111. 



Write Microcontroller Memory, $08 

This command writes a value into the ADB microcontroller RAM, It is a 3-byte 
Command The first byte has a value of %0000100O. The second byte is the address to 
write into. The third byte is the value to be written. 



Read Microcontroller Memory, $09 

This command reads a byte from the ADB microcontroller memory. The command 
reads ROM or RAM locations, depending on the value of the high byte of the address 
sent for reading. This is a 3-byte command. The value of the first byte is %0QQ01O01. 
The second byte is the low byte of the microcontroller address. The third byte is the 
high byte of the microcontroller address, If the third byte is 0, RAM is read; otherwise, 
ROM is read. This command returns 1 byte. 



Read Modes Byte, $0A 

This command reads the modes byte Csee "Set Modes, $Q4" or "Clear Modes, $05"). 
Itis a 1-byte command with a value of %000010H3l It returns 1 byte. 
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Read Configuration Bytes, $0B 

This command read? configuration bytes. Ti is a 1-byte command with a value of 
%0000l0ll. This command returns to the 65C816 (through ihe data latch in the GUI) a 
total of 3 bytes (presented one at a time for reading by the 65C816) representing the 
most recently set configuration (from the mosi recent Set Configuration Bytes 
command). The 3 bytes are returned in the following sequence: 



ADB mouse address 
ADB keyboard address 



Sets character set (needed for certain languages) 
Sets keyboard layout language (see Table 9-2) 



Sets delay to repeat rate (3 bits) 



Byte I 

High nibble 
Low nibble 

Byte 2 

High nibble 
Low nibble 

Byte 3 

High nibble 

1/4 sec 

1 1/2 sec 

2 5/4 sec 

3 1 sec 

4 No repeat 

Low nibble Sets auto -repeat rate (3 bits) 

1 30 keys/sec 

2 24 keys/sec 

3 20 keys/sec 

4 15 keys/sec 

5 11 keys/sec 

6 8 keys/sec 

7 4 keys/sec 



Read and Clear Error Byte, $0C 

This command returns the ADB error byte to the data laich in the GL1 ". H dears the 
ADB error byte to zero It is a 1-bycc command with a value of %00001 100. This 
command is useful for hardware developers dehugging new ADB devices. 



Get Version Number, $0D 



This command returns the device version number into the data latch in the GLU. It is a 
]-byte command wiih a value of %0000t101. 
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Read Available Character Sets, SOE 

This instruction reads available character sets. It is a 1-byte command with a value of 
%00001110. The first byte value returned specifies how many character-set identifiers 
follow this first byte. Subsequent bytes returned! through the data latch identify the 
character sets. This command is used by the Control Panel to determine which 
character sets are available in the system. It is assumed that each microcontroller is 
paired with a specific megachip. However, when the Apple HCIS is manufaciurcd, the 
factory may install one type of megachip and a different type of microcontroller. This 
command allows the system to correctly match the capabilities of the megachip with 
the microcontroller that is actually installed in the system. 

The order in which the character sets are returned is imporiant. The first number 
returned corresponds to character set in the megachip; ihe next number 
corresponds to character set 1 , 



Read Available Keyboard Layouts, SOF 

This command (%00OOTlll) returns the number of keyboard layouts available. Tliis 
command is used by the Control Panel to determine which keyboard layouts are 
2vailable in the system. Like the Read Available Character Sets command, the order in 
which the numbers are returned is important. The first number returned represents 
layout in the microcontroller. 



Reset the System, $10 

This command resets the system and pulls the reset line low for 4 milliseconds. It is a 
1-byte command with a value of %00010000. 



Send ADB Keycode, $11 

This command is used to emulate an ADB keyboard by accepting ADB keycodes from 
a device and then sending them lo the microcontroller to be processed as keystrokes 
This command does not process cither reset-up or reset-down codes; these reset 
keycodes must be processed separately. This command can be used to detect key-up 
events or to emulate a keyboard with another device, such as might be used for the 
handicapped. This is a 2-byte command. The first byte has a value of %000t0oT)1 , the 
second byte contains the keystroke lo be processed See the Apple lies Hardu 
Reference fas details about the values that correspond to .specific key- down, key-up 
sequences. 
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Reset AD B, $40 

This command pulls ihe ADB low for 4 milliseconds- Care must be taken with this 
command because rescuing an ADB keyboard clears any pending commands, 
including all key-up events. This means that ir this command is issued as a result of a 
key being pressed, when the key is released, the key-up code will be lost and the key will 
autorepeat until another key is pressed All keys should be up before this command is 
executed. This is a 1-byte command with a value of%01000000, 



Receive Bytes, $48 

This command is used to receive data from an ADB device. This is a 2-byte 
command. The first byte value is 9*01001000. The second byte value is a combination 
of (he ADB command (see the Apple JIGS JJardware Reference) in the high nibble 
and the device address in ihe low nibble. The microcontroller sends this ADB 
command byte on the ADB and then waits for the device to return data. The 
microcontroller then returns the data bytes to the system in the opposite order that 
they were received from the ADB. (The issuer of this command must know about ADB 
commands and the values they return.) 



Transmit num Bytes, $49-$4F 

This command is used to transmit data to an ADB device. This is a 3- to 9-byte 
command. The first byte value is the Transmit command itself and has a value of 
%010Qlnum, where num is a set of 3 binary bits that represent a number. The value of 
(num + 1) specifics how many data bytes will be transmitted as part of this command, 
The second byte value is an actual ADB command. The third and subsequent bytes 
(num + 1) arc bytes that are transmitted directly to the devices on the ADB bus 
immediately following the ADB command. 



Enable Device SRQ, $50-$5F 

This command enables an SRQ (service request) on the ADB device at address abed. 
It is a l-byte command with a value of %0101abcd 
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Flush Device Buffer, $60-$6F 

This command flushes the ADB device buffer at address abed, It is a I -byte command 
with a value of %QT lOabcd. 






Disable Device SRQ, $70-$ 7F 

This command disables the SRQ on an ADB device aL address abed M Is a 1-byte 
command with a value of Will abed. 






Caution 

If data Is pending when this command Is executed, the pending data could be 
lost. For example. If SRQ Is disabled on the ADB keyboard, then all key-up codes 
could be lost. See 'Reset ADB, $40,* 



Transmit Two Bytes, $80-$BF 

This command transfers 2 bytes of data (data and status in forma, lion) from 3 specific 
device using the ADB Listen command (see (he Apple IfGS Hardware Refenmciiy li is 
a 1-byte command with a value of %10xyabcd r where xy is the register number and 
abed is the device address. 






Pol! Device, $C0-$FF 

This command is used lo gel data from a specific device. It uses the ADB Talk 
command. After the Talk command is executed, the microcontroller wails for the 
device to send back data or for timeout. The microcontroller wails until all data has 
been received and then returns a status byte (see Table 9-3) to the system indicating 
the number of bytes received and then returns the data. Il returns the bytes in an order 
opposite that in which they were received by the ADB. This is a 1-byte command with 
a value of %1 lxyabcd, where xy is the register number and abed is the ADR device 
address. 

♦ Note: All commands (except the Sync command) that require more than a 1-byte 
transfer automatically return timeout in 10 milliseconds if there is no response The 
Sync command may require 20 milliseconds to process the ADB address byte. 
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Microcontroller status byte 

The ADB microcontroller sends a status byle to the system when it detects one of the 
conditions listed in Table 9-3- When the system receives the microcontroller status 
byte, a system interrrupt occurs, The system then determines which of the conditions 
caused the interrupt and jumps to the appropriate vector. 1 Tie responses to these 
interrupts are as follows: 

■ Response byte: Jumps to the response vector and processes incoming data from 
the microcontroller. 

■ Abort/ flush: Jumps to the abort vector and attempts to resynchronize the system 
with the Apple DeskTop Bus-, if this fails, a system error occurs. 

■ Desktop Manager key sequence: jumps to the Desktop Manager vector. 

■ Flush buffer key sequence: Jumps to the flush buffer vector, 

■ SRQ: Jumps to the SRQ handler that is used Co gather data from the ADR devices, 
(This interrupt occurs if the device has some data that it wants to transmit. The 
device generates a service request to catch the attention of the microcontroller.) 

Table 9-3 

Status byte returned by microcontroller 

Bif Condition 



7 Response byte if set; otherwise, status byte 

6 Abort/flush 

5 Desktop Manager key sequence pressed 

4 Flush buffer key sequence pressed 

3 SRQ valid 

2-0 If all bits are dear, then no ADB data is valid; if data is available, then the bits 
indicate the number of valid bytes received minus 1 — between 2 and 8 bytes 
total (001 means 2 bytes ready, Oil means 4 bytes, and so on). 
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This chapter describes the Apple IIGS mouse firmware. You can read the mouse 
position and ihe status of the mouse buttons using this firmware. 



Important 

The material in rhts manual regarding soft switches and hardware registers tor the 
Apple IIgs mouse firmware Is provided for Information only. Applications must use 
the firmware calls only if they wish to be compatible with the mouse device used 
In all Apple II systems. 



The Apple lies mouse is an intelligent device thai uses the Apple DeskTop Bus CADB) 
to communicate with the Apple II GS ADB microcontroller This is a departure [rum 
the AppleMouse™ card and the Apple He mouse interface, each of which depends 
extensively on firmware to support the mouse. The Apple IIGS mouse firmware has a 
true passive mode like the AppleMouse, but it differs from the Apple lie mouse, which 
requires interrupts to function 

Certain devices, to operate properly, must be the sole source of interrupts within a 
system because they have critical times during which they require immediate service 
by the microprocessor. An interrupting communications card is a good example of a 
device that has a critical service interval. If it is not serviced quickly, characters might 
be lost. "Hie true passive mode permits such devices to operate correctly. The passive 
mode also prevents the 65C816 from being overburdened with interrupts from the 
mouse firmware, as can occur in the Apple He if the mouse is moved rapidly while an 
application program is running. 

The Apple lies mouse firmware can cause an interrupt only if all of the following 
conditions are true: 

□ The interrupt mode is selei 

n The mouse device is on. 

11 An interrupt condition has occurred. 

a A vertical blanking signal (VBL) has occurred. 

Unlike the Apple lie mouse, which interrupts whenever the mouse device is moved, 
the Apple IIC.S mo ire interrupts in synchronization with the VBL. Hits 

automatically limits the total number of mouse firmware interrupts to 60 per second, 
cutting down on the overhead the mouse device puts on the 65C816. If an interrupt 
condition (determined by the mode byte setting) occurs, it will be passed to the 
65C816 only when the next VBL occurs. 



Warning 

Because the mouse firmware information is updated only once each vertical 
blanking Interval, your program must be certain that at least one vertical 
blanking Interval has elapsed between mouse reads if it expects to obtain new 
Information from the mouse device. 
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Mouse position data 

When the mouse is moved, data is returned as a delta move as compared to its 
previous position, where the change in X or Y direction can be as much as to ± 63 
counts. The maximum value of 63 in either direction represents approximately 0.8 
inch of travel. 

* Note: A delta move represents a number of counts change in position as compared 
to the preceding position that the mouse occupied. The Apple IIgs mouse firmware 
converts this relative-position data (called a delta) to an absolute position. 

The mouse device also provides the following information to the mouse firmware: 
□ current button and button 1 data (1 if down, if up) 
u delta position since last read 

* Note.- At power up or reset, the GLU chip enters a noninterrupt stale and also turns 
the mouse interrupts off. 

The ADB microcontroller automatically processes mouse data. The microcontroller 
periodically polls trie mouse to check for activity. If the mouse device is moved or its 
button is pushed, 2 bytes are sent Lo the microcontroller. The microcontroller sends 
boih mouse data bytes to the GLU chip (byte Y followed by byte X; this enables the 
interrupt). The 65C816 then checks the status register to verify that a mouse interrupt 
has occurred, the 2 data bytes have been read, and mouse byte Y was read first, The 
GLU chip clears the interrupt when the second byte has been read. To prevent 
overruns, the microcontroller writes mouse data only when the registers are en 
(after byte X has been read by the system). Table 10-1 shows the 16 bits returned by the 
Apple II GS mouse firmware. 

Table 10-1 

Apple IIgs mouse data bits 



Bit 



Function 



Button status 

Y movement (negative ■ up, positive ■ down) 

Button 1 status 

X movement (negative = left, positive = right) 



Mouse position data 




Register addresses— firmware only 

Table 10-2 shows ihe contents of the register addresses that the ADB microcontroller 
uses to transitu! Apple lies mouse data and status information to the 65C816. 

Table 10-2 

Apple IIgs mouse register addresses 



Address Fun cf Ion 


SC027 GLU status register, defined as follows: 


Bit = d 


Must not be altered by mouse 


Bit I - 


X position available Cread only) 


Bil 1 - 1 


Y position available (read only) 


Bk 2 = k 


Musi not be altered bv mou.se 


Bil 3 - k 


Must not be altered by mouse 


Bit A = d 


Must not be altered by mouse 


Bit 5 = d 


Must not be altered by mouse 


Bit 6 = 1 


Mouse interrupt enable (read or write) 


Bit 7 - 1 


Mouse register full (read only) 


k 


Used by keyboard handlers 


d 


Used by ADB handlers 



SCO 2 4 Mouse data register: 

First read yields X position data and button 1 data. 
Second read yields Y position data and button data. 

To enable mouse interrupts, set bil 6 of location $C027 to 1. Recall however, that only 
this bil and no oLher should be changed. This entails reading the current contents, 
changing only that single bit and then writing the modified value back into ihe register. 

If mouse interrupts are enabled, the firmware determines whether the interrupt came 
from the mouse by reading bits 6 and 7 of AC027-, if both bits - 1, then a mouse 
interrupt is pending. 



Reading mouse position data —firmware only 

Hie following sequence of steps mu>t :v laken, in this «i« I order, foi accurate mouse 
readings to be obtained. Failure lo perform the steps in this order will necessitate 
some corrective action because the data will be contaminated. Con lamina ted data is a 
condition that occurs when the X and Y values that you arc trying to read are from 
different VBL reads of the mouse, 

□ Read bit 7 of 5C027. 

If bit 7 = 0, then X and Y data is not yet available. 

If bil 7-1, then data is available, but could be contaminated. 
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D Read bit 1 of $C027 only if bit 7 = 1, 

If bit 1 = 0, then X and Y data are not contaminated and can be react The first read 
of $C024 returns X data and button 1 data; the second read of 5C024 returns Y data 
and button data. 

Use caution when using indexed instructions. The false read and write results oF 
some indexed instructions can cause X data to be lost and Y data to appear where X 
data was expected. 

If bit 1 = 1 and 3C024 has not been read, then the data in $C024 is contaminated 
and must be considered useiess. If this condition occurs, perform the following 
steps: 

D Read $C024 one lime only. 

□ Ignore the byte read in. 

Exit the mouse read routine without updating the X, Y, or button data. This will not 
harm the program; however, it guarantees that the next time the program reads mouse 
positions j the positions will be accurate. 

The data bytes read in contain the following information: 

i X data byte 

If bit 7 = 0, then mouse button 1 is up. 
If bit 7 = 1 , then mouse button 1 is down. 

■ Bit 0-6 delta mouse move 

If bit 6 = 0, then a positive move is made up to S3F (633* 

If bit 6=1, then a negative move in two's complement is made up to SAO (64). 

■ Y data byte 

If bit 7 a 0, then mouse button is up. 
If bit 7 = 1, then mouse button is down 

■ Bit 0-6 delta mouse move 

If bit 6 = 0, then a positive move is made up to $3F (63). 

If bit 6 = 1, then a negative move in two's complement is made up to S40 (64). 






Position clamps 

When the mouse moves the cursor across the screen, the cursor is allowed to move 
only within specified boundaries on the screen. These boundaries are the maximum 
cursor positions on the screen in the X and Y directions. These maximum positions 
are indicated to the firmware by clamps, 

Gamps arc data values that specify a maximum or minimum value for some other 
variable. In this instance, the mouse clamps specify the minimum and maximum 
positions of the cursor on the screen. 

The mouse clamps reside in RAM locations reserved for the firmware. You should 
only access these locations using the Apple UGS tools. 
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Using the mouse firmware 

You can use the mouse firmware by way of assembly language or BASIC. There are 
several procedures and rules to follow to be effective in either language. The following 
paragraph? outline these procedures and rules and give examples of the use of the 
mouse firmware from each of these languages- 



Firmware entry example using assembly language 

To use a mouse routine from assembly language, read the location corresponding to 
the routine you want to call (see Table 10-4 at the end of this chapter! The value read 
is the offset of the entry point to the routine to be called, 

4 Note: Interrupis must be disabled on every call to the mouse firmware. 

The following assembly code example correctly sets up the entry point for the mouse 
firmware. Note that n is the slot number of the mouse. To use the code, you must 
decide which mouse firmware command you wish to use and then duplicate the code 
for each of the routines you use. For example, to use SERVEMOUSE from assembly 
code, you would replace the line SETMENTRY lda SETMOUSe with a line that reads 
SERVEMENTRY LDA SERVEMOUSE, where SERVEMOUSE is SCnlJ. Table 10-4 
defines all of the offset locations for the built-in mouse firmware routines. 

,'Offset to SETMOUSE offset (SC412 for Apple lies) 
/Get offset into code 
i Modify operand 
/Where Cn - CA in Apple lies 
/Where n = 40 in Apple Ilfis 
/Save interrupt, status 
/Guarantees no interrupts 
/Turn mouse passive mode on 
jJ3R to d modified JMP instruction 
fC - 1 if illegal -mode -entered error 
,-Restore interrupt status 
/Exit 

/Restore interrupt status 
fEx.it to error routine 

.■Modified operand for correct entry paint; ScflOO for 
Apple IIgs 






SErMOUSE 


EQU 


SCnl? 


SETMENTRY 


LDA 


SETMOUSE 




STA 


TOMODSE +2 




LDX 


Cn 




LDY 


no 




PHP 






SEI 






LDA 


*S01 




JSR 


TOMODSE 




BCS 


ERROR 




F1P 






Ria 




ERROR 


?! v 






JMP 


EBRORMF- 


TOMODSE 


•"•■:- 


SCnOO 
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Firmware entry example using BASIC 

To lurn ihe mouse on using BASIC, execute the Following code: 



PRINT CFiRSC*.) ;"PR#4" ;REN 

CHR [1] :BEM 

PRINT CHR$ 111 ;"PR#0" J REM 



Mouse ready for output 

1 turns the mouse on rrnm basic 

ftafti dt« scree i out bu1 



<« Note; Use PRINT CHR$ (4) ; "PR#3" lo return lo 80-colum.n mode. 

To accept outputs from BASIC, the firmware changes the output lin'cs at $36 and 537 lo 
poini lo SC407 and performs an INITMOUSE routine (resets the mouse clamps to their 
default values and positions the mouse to location 0,0). 

m the mouse off, execute the following BASIC program; 

Mouse lead/ lor output 

turns the mouse off from BASIC 

Restore screen output 

"PRfS'* to return to 80 columns. 

!. read mouse position and button statuses from BASIC, execute the following code: 



PRINT 


CHR3M) ; " 


PR#4" 


:REM 


' 




(0) 




:REM 


r /::r; 


CKRS(4) ; " 


&M0" 


:REM 


♦ Mute Use 


PRINT 


CHR$ < 4 ) 



PRINT CERS(fl); "IN«4" 

x, y, a 

PRINT CHRS(4); "INdC" 



:rem Mouse ready for I- 
•REM Lnput mouse position 

:REM Return Keyboard as the input device when 
positions have been reab 



When the mouse is turned on from BASIC (for data entry), the firmware changes the 
input links at S38 and $39 to point to $C405. When you execute an INPUT statement 
while the input link is set for mouse input, the firmware performs a READMOUSE 
operation before converting the screen-hole data to decimal ASCII and places the 
converted input data in the input buffer at $200. 

In BASIC, the mouse runs in passive mode or a noninterrupi mode. Clamps are set 
automatically to 0000-1023 CS00O0-SO3FF) in both the X and the Y direction, and 
m data in the screen holes are set lo 0. 

During execution of a BASIC INPUT statement, lhe firmware reads the position 
changes (deltas) from the ADB mouse and adds them to the absolute position in the 
screen holes, clamping the positions if necessary, and converts the absolute positions 
in the screen holes to ASCII format. The firmware then places dial daia, with the 
button status, in the input buffer, issues a carriage return, and returns to BASK 

* Mo*@f lhe term screen holes has absolutely nothing to do with the appearance of 
anything on the actual display. Screen holes are simply unused bytes in lhe memory 
area normally reserved for screen-display operations. Because screen holes are 
unused by Lhe display circuitry, they can be used by Lhe firmware for other 
purposes. 
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Reading button 1 status 

Button 1 status cannot be returned to a BASIC program. This would add another input 
variable to the input buffer, and an error message that states ? EXTRA IGNORED 
would be displayed. 

If you want to read button 1 status, you can use the BASIC Peek command to read the 
screen hole that contains that data. The data returned to the input buffer is in the 
following form: 

s xl x2 x3 X'': X5, a yl y2 y3 y4 y5, sb BO b5 cr 

where 

a = Sign of absolute position 

xl . . .x5 = Five ASCII characters indicating the decimal value of X 

yi , . „y5 = Five ASCII characters indicating the decimal value of Y 

ab = Minus sign (-) if key on keyboard was pressed during INPUT statement 
entry and plus (+) if no key was pressed during INPUT statement entry 

BO = ASCII space character 

b5 ■ 1 if button is pressed now and was also pressed during last INPUT 
statement entry 

» 2 if button is pressed now but was not pressed during last INPUT 
statement entry 

- 3 if button is not pressed now but was pressed during last INPUT 
statement entry 

= 4 if button is not pressed now and was not pressed during last INPUT 
statement entry 

er ■ Carriage return (required as a terminator before control is passed from 
firmware back to BASIC) 

♦ Note: The BASIC program must reset the key strobe at $C010 if sb returns to a 
negative state. POKE 49168,0 resets the strobe. 

The mouse is resident in the Apple IIgs internal slot 4. When the mouse is in use, the 
main memory screen holes for slot 4 hold X and Y absolute position data, the current 
mode, button 0/1 status, and interrupt status. Flight additional bytes are used for 
mouse information storage; they hold the maximum and minimum clamps for the 
mouse's absolute position. 

Table 10-3 shows the mouse's screen-hole use when Apple IIGS firmware is used. 
Figures 10-1 and 10-2 show how the bits of the button interrupt status byte and the 
mode byte are assigned. 
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Table 10-3 

Position and status Information 



Address 



Us« 



$47C Low byte of absolute X position 

$4FC Low byte of absolute Y position 

S57C High byte of absolute X position 

$5FC High byte of absolute Y position 

$67C Reserved and used by firmware 

$6FC Reserved and used by firmware 

$77C Buuon 0/1 interrupt status byte Csee Figure 10-1) 

n Mode byte Csee Figure 10-2) 



Figure 10-1 

Button Interrupt status byte, S77C 



Previously, button 1 was up/down CO/ ID 
Movement interrupt 
Button 0/1 interrupt 
VBL Interrupt 

Currently, button 1 Is up/down (0/1) 
X/Y moved since last READMOUSE 
Previously, button 1 wos up/down C0/1) 
Currency, button 1 Is up/down (0/1) 






Figure 10-2 

M9d§ &yr§ ; §7FG 



Mouse oft/on (0/1) 

Interrupt on next VBL it mouse Is moved 

Interrupt on nexl veil it carton is pressad 

Interrupt on VflL 

Reserved 






Reserved 
Reserved 
Reserved 



'Used by firmware only 



Using the meme fiFfflwsF§ 20§ 



Mouse programs in BASIC 

Two program examples are provided below, The first example, Mouse.Move, reads 
and displays the mouse position information. The second example is called 
Mouse. Draw and allows you to make simple drawings on the screen in low-resolution 
graphics mode. 



Mouse. Move program 

10 HOKE 

20 PRINT "MOUSE. MOVE DEMO" 

30 PRINT CHRS<<n;"Pfi#<3"EPRINT CHRSUJ 

40 PRINT CHR5f.il J ?"PR#0" 

50 PRINT CHRS (4J;"IN#4" 

6D INPUT M,, ;X,y,S 

TO VTAB 10s PRINT X;" "Y" "S M 

80 3F S > THEN 60 

3 P R 1 N T CHRS M J f " I N* 0" 

100 PRINT CHRS (41 ( -"FRt4" : PRINT CHRS<0) 

110 PRINT CHRS («) ;"PR#0" 

Comments 

Line 10 dears the screen to black. 
Line 20 prints a heading message. 
Line 30 starts up the mouse's internal program. 

Line 40 establishes that subsequent PRINT commands will send information to the monitor 

screen. 

Line 50 establishes that the subsequent INPUT command will read the mouse. 

Line GO transfers mouse position and button status readings to the numeric variables X, Y 

and S. 

I in. 70 displays the numeric variables X, Y, and S on the 10th line of ihe monitor screen. 

Line 80 returns the program for more mouse data if no keyboard key has been pressed. If a 

key has been pressed, the program drops to line 90. 

Line 90 reestablishes your keyboard as the input device. 

Line 100 reset? the mouse position data to zero. 

Line 110 reestablishes the monitor screen as Ihe output device. 

Line 120 ends the program, 
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Mouse.Draw program 




REM MOUSE, DRAW Uses mouse to draw lo-res graphics 

GOSUB 1000; REM TURN ON THE MOUSE 

PRINT CHRSHWTNH" 

INPUT "";X, Y,5:REM READ MOUSE DATA 

IF 5=1 THEN 100:REH CLEAR THE SCREEN 

IF 5<0 THEN 300, -REN TIME TO QUIT? 

REM SCALE MOUSE POSITION 

X-INTtX/^S.STSJ 

Y=IST(¥/25.575) 

PLOT X r Y 

GOTO 120 

REM CHECK EF TIME TO QUIT 

PRINT CBR${4) ,-"IN#Q n 

VTAB 22 j PRINT "PRESS RETURN TO CONT OR ESC TO QUIT" 

VTAB 22:HTAB 39iGET ASiPOKE -16368,0 

IF AS"»CHR${23} THEN HOHE : GOTO 110 

IF ASOCHRS (27> THEN 330 

REM CLEAR SCREEN AND ZERO MOUSE 

TEXT: ROME 

PRINT CHRSH) ;"PRffV : PRINT CHRS(1J 

PRINT CHR$(4) ;"PR#0'' 

END 

REM Clear the screen and initialize the mouse 

KGME ; GH 

COLOR - 15 

PRINT CKRS<4) ; "PR#4 n :FRINT CHRS{1) 

PRINT CHR$<4);"PR#0" 

RETURN 















Mouse programs in BASIC 



207 






Comments 

Line 10 reminds you what ihe program does. 

Line 1 00 calls ihc subroutine at lines 1000 through 1Q5G 

Line 110 establishes thai the subsequent INPUT command will read the mouse. 

Line 120 transfers mouse position and button status data to the numeric variables X, Y, and 5. 

Line 130 reinitializes the mouse if Its button is pressed. 

Line HO sends the program to its exit routine if a key on the Apple keyboard has been 

pressed. 

Line 150 reminds you what (he next two lines do. 

Lines l60 and 170 convert the range of mouse posiiion numbers (0 to 1023) to the range of 

low resolution graphics coordinates (0 to 40). 

Line 180 plots a point on the monitor screen, 

Line 190 sends the program back for more mouse data. 

Line 300 reminds you what lines 310 through 400 do. 

Line 310 tells the computer lo accept input from its keyboard. 

Line 320 prints prompting instructions on line 22 of the screen. 

Line 330 fetches your answer to the prompt and changes ihc bullon status number back to 

positive (it becomes negative whenever you press a key on the Apple keyboard). 

Line 340 sends the program back lo reporting mouse data if you pressed Return 

Line 350 fetches another answer if you press any key except Esc. 

Line 360 reminds you what happens next. 

Line 370 cancels graphics mode and clears the screen 

Line 380 resets the mouse position data to zero. 

Line 390 reestablishes the monitor screen as the output device. 

Line 400 ends the program. 

Line 1000 reminds you what the following subroutine does. 

Line 1010 clears the monitor screen and sets up Apple's low-resolution graphics mode. 

1 inc 1020 establishes that the cursor will be white. 

Line 1030 starts up the mouse's Internal progTam. 

Line 1040 establishes that subsequent PRINT commands will send information lo the monitor 

screen. 

Line 1050 returns to the main program (line 100). 
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Summary of mouse firmware calls 

The firmware calls to enter mouse routines are listed in Table 10-4. These calls 
conform to Pascal 1.1 protocol for peripheral cards. 

Table 10-4 

Mouse firmware calls 



Location 



Boutin* 



Definition 



SC40D 




PI NIT 


$C40E 




PR RAD 


tcro 




PWRITE 


$C410 




PSTATUS 


5C411 = 


soo 




Routines implemented on Apple IIG! 


$C412 




5ETMOUSE 


SC413 




SERVEMOUSE 


SC414 




READMOUSE 


SC415 




CLEARMOUSE 


SC416 




POSMOUSE 


SC417 




CLAMP MO USE 


SC418 




IIOMEMOUSE 


SC419 




INITMOUSE 



Pascal firmware entry points for Ihe mouse 

Pascal 1N1T device (not implemented) 
Pascal READ character (not implemented) 
Pascal WRITE character (not implemented) 
Pascal get device status (not implemented) 
Indicates that more routines follow 



Sets mouse mode 

Services mouse interrupt 

Reads mouse position 

Clears mouse position to (for delta mode) 

Sets mouse position to user-defined position 

Sets mouse bounds in a window 

Sets mouse to upper-left corner of clamping window 

Resets mouse damps to default values; Sets mouse 

position to 0,0 



Entry points compatible with AppleMouse card; fhey do nothing In Apple ItGS 

Dummy routine; clears c and performs an RTS 

Dummy routine; dears c and performs an RTS 

Dummy routine; clears c and performs an RTS 
Dummy routine, clears c and performs an RTS 
Dummy routine; dears c and performs an RTS 
Dummy routine-, dears c and performs an RTS 



Initial entry point when coming from BASIC 

BASIC input entry point (opcode SEC) Pascal ID 

byte 

BASIC output entry point (opcode CLC) Pascal ID 

byte 

Pascal generic signature byte 

Apple technical -support ID byte 

Additional ID byte 

Summary of mouse firmware calls 



5C41A 




D1AGMQUSI: 


SOUB 




COPYRIGHT 


$C41C 




TIM ED ATA 


SC41D 




SETVBLCNTS 


$C4tE 




OPT MOUSE 


$C41F 




STARTTIMER 


Other significant locations 


SC400 




B1NITENTRY 


SC405 




BASICIKPUT 


SC407 




BASICOUTPUT 


m. ■<!.,-; 


501 




$C4QC = 


$20 




SC4FD ■ 


SD6 
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Pascal calls 

Pascal recognizes the mouse as a valid device; however, Pascal is noi supported by the 
firmware, A Pascal driver for the mouse is available from Apple to interface programs 
with the mouse. Pascal calls PInit, PRead, PWrite, and PSlatus return with the X 
register set to 3 (Pascal illegal operation error) and the carry flag set lo 1, Following is a 
list of Pascal firmware calls. 



PInit 

Function 

Input 

Output 



Not implemented (just an entry point in case user calls it by mistake). 

All registers and status bits. 

X = $03 (error 3 = bad mode: illegal operation), c = 1 (always). 
Screen holes; unchanged. 



PRead 

Function 

Input 

Output 



Not implemented (just an entry point in case user calls it by mistake). 

All registers and status bits, 

X » $03 (error 3 = bad mode; illegal operation), c = 1 (always). 
Screen holes: unchanged. 



PWrite 

Function 

Input 

Output 



Not implemented (just an entry point in case user calls it by mistake). 

All registers and status bits. 

X = $03 (error 3 * bad mode: illegal operation), c = I (always). 
Screen holes: unchanged 



PStatus 

Function 

input 

Output 



Not implemented (just an entry point in case user calls it by mistake), 

All repier§ and status bits. 

X - S03 (error 3 = Bad mode.; illegal operation), c ■ 1 (always). 
Screen holes: unchanged. 
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Assembly-language calls 

This seciion describes ihe assembly-language firmware calls. When you use the mouse 
from assembly language, you musi keep several items in mind. 

D For built-in firmware, n = mouse sloe number A. 

□ The following bite and registers are not changed by mouse firmware: 

D e, m, I, x 

D direct regisier 

n data bank register 

□. program bank register 

a Mouse screen holes should not be changed by an application program, with one 
exception: During execution of the POS.MOUSK function, new mouse coordinates 
are written by the application program directly inio the screen holes. No other 
mouse screen hole can be changed by an application program without adversely 
affecting the mouse, 

D The 65C816 assumes that trie mouse firmware is entered in the following machine 
slate: 

□ 65CS16 is in emulation mode, 
a Direct register = SOOOO. 

a Data bank register = $00. 

□ System speed = fasl or slow (does not matter which), 

□ Text page 1 shadowing is on to allow access to screen-hole data. 

Here are the actual firmware routines. Notice thai each is specified by its offset entry 
address. Recall that the offset entry point is a value at a given location (for example, 
SOI 12) to which you add the value of the main entry point (for example, SC400) to ' 
obtain the actuaJ address to which the processor must jump to execute the routine. 



SETMOUSE, $C4I2 

Function Sets mouse operation mode. 

Input A = mode ($00 to $0P are the only valid modes). 

X = Cn for standard interface (Apple IIG5 mouse not used). 
Y = nO for standard interface (Apple IIG5 mouse not used). 

Output A = mode if illegal mode entered; otherwise. A is scrambled 

X, Y, V, N, Z - scrambled, 
c = if legal mode entered (mode is <= $0h"). 
c = 1 if illegal mode entered (mode is > $0F). 
Screen holes: Only mode bytes are updated. 
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SERVEMOUSE, $C413 

Function Tests for interrupt from mouse and resets mouse's interrupt line. 

Input X = Cn for standard interface (Apple IIGS mouse not used). 

V = nO for standard interface (Apple IIGS mouse not used). 

Output X, Y, V, N. 2 = scrambled 

c ■ if mouse interrupt occurred. 

c = 1 if mouse interrupt did not occur, 

Screen holes; Interrupt status bits updated to show current Status. 



READMOUSE, $C414 

Function Reads delta CX/Y) positions, updates absolute X/Y positions, and reads 

button statuses from ADB mouse- 
Input A - not affected. 

X • Cn for standard interface (Apple IIGS mouse not used). 

Y = nO for standard interface (Apple IIGS mouse not used). 

Output A, X, Y, V, N, 2 = scrambled. 

c - (always). 

Screen holes: SLO, XHI, YLO,, YHI buttons and movement status bits 
updated; interrupt status bits are cleared, 



CLEARMOUSE, $C415 

Function Resets buttons, movement, and interrupt status to 0, X, and Y. ("ITiis 
mode is intended for delta mouse positioning instead of the normal 
absolute positioning.) 

Input A = not aFfecied. 

X = Cn for standard interface (Apple IIGS mouse not used). 
Y - nO for standard interface (Apple IIGS mouse not used). 

Output A, X, Y, V, N, Z = scrambled, 

c = (always). 

Screen holes: SLO, XHI, YLO, YHI buttons and movement status bits 
updated; interrupt status bits are cleared. 
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POSMOUSE, $C416 



Function 
Input 



Output 



Allows user to change current mouse position. 

User places new absolute X/Y positions directly in appropriate screen 

holes, 

X = Cn for standard interface CAppie IIGS mouse not used). 

Y ■ nO for standard interface (Apple IIGS mouse not used). 

A, X, Y, V, N, 2 - scrambled, 

c = (always). 

Screen holes: User changed X and Y absolute positions only; bytes 

changed. 



CLAMPMOUSE, $C417 



Function 



Input 



Sets up clamping window for mouse use. Power-up default values are 
to 1023 (S000O to J03FF). 

A = if entering X clamps. 
A - 1 if entering Y damps. 

Clamps arc entered in slot screen holes by the user as follows: 

$478 - low byte of low clamp. 
$4FB = low byte of high clamp. 
$578 = high byte of low damp. 
S5F8 = high byte of high clamp. 

X = Cn for standard interface (Apple IIGS mouse not used), 
Y = nO for standard interface (Apple IIGS mouse not used). 

A, X, Y, V, N, 2 = scrambled. 

c - (always). 

Screen holes: X/Y absolute position is set to upper-left corner of 

damping window. Clamping RAM values in bank SEO are updated. 

* Abie.- The Apple ires mouse firmware performs an automatic HOMEMOUSE 
operation after a CLAMPMOUSE HOMEMOUSE execution is required because the 
delta information is being fed to the firmware instead of ±l's, as in the case of the 
Apple II mouse and the 6805 AppleMouse microprocessor card. The delta 
information from the Apple IIGS ADR mouse alters the absolute position of the 
screen pointer, using clamping techniques not used by the other two mou.se 
devices. 



Output 
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HOMEMOUSE, $C418 

Function Sets X/Y absolute position to upper-left corner of clamping window. 
A - not affected. 



Input 



Output 



X = Cn for standard interface (Apple ITgs mouse not used). 
Y = nO for standard interface (Apple I1GS mouse not used). 

A, X, Y, V, N, Z - scrambled. 
c ■ (always) 

Screen holes: User changed X and Y absolute positions only, bytes 
changed. 



INITMOUSE, $C419 



Function 

Input 

Output 



Sets screen holes to default values and sets clamping window to defaul 
value of 0000 to 1023 ($0000, $03FF) in both the X and Y directions; 
resets GLU mouse interrupt capabilities. 

A = not affected. 

X - Cn for standard Interface (Apple UCJS mouse not used). 

Y = nO for standard interface (Apple IIGS mouse not used). 

Z = scrambled. 



A, X, Y, V, N L 

c ■ (always) 

Screen holes: X/Y positions, button statuses, and interrupt status are 

reset. 

«S* Note: Button and movement statuses are valid only after a READMOUSE operation. 
Interrupt status bits are valid only after a SERVEMOUSE operation. Interrupt status 
bits are reset after READMOUSE. Read and use or read and save the appropriate 
mouse screen-hole data before enabling or reenabling 65C816 interrupts. 
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Appendix A 



Roadmap to 
the Apple IIgs 
Technical Manuals 



The Apple IIGS personal computer has many advanced features, making it more 
complex than earlier models of the Apple II. To describe it fully, Apple has produced 
a suite of technical manuals. Depending on the way you intend to use the Apple HGS, 
you may need to refer to a select few of the manuals, or you may need to refer to most 
of them. 

The technical manuals are lisLcd in Table A-]. Figure A-l is a diagram showing the 
relationships among the different manuals. 
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Table A- 1 

Apple llss technical manuals 



TiJIe 



Sub Joe I 



Technical Introduction to the Apple IFGS 

Apple FFGS Hardware Reference 

Apple FFGS Firmware Reference 

Programmer's Introduction 
to the Apple II gs 

Apple FIGS Toolbox Reference, 

Volume 1 

Apple FIGS Toolbox Reference, 
Volume 2 

Apple IIGS Programmer's Workshop 
Reference 

Apple FIGS Programmer's Workshop 
Assembler Reference 

Apple IIGS F^rogrammer's Workshop 
C Reference 

ProF)OS 8 'Technical Reference Manual 

Apple IIGS ProFX}S 16 Reference 

Human Interface Guidelines. 

The Apple Desktop Interface 

Apple Numerics Manual 



What the Apple IIGS is 
Machine internals — hardware 
Machine internals — firmware 
Concepts and a sample program 

I low the tools work and some toolbox 
specifications 

More toolbox specifications 
The development environment 

Using the AP W assembler 
Using C on the Apple IIGS 

Standard Apple II operating system 

Apple IIGS operating system and System 
Loader 

Guidelines for the desktop interface 
Numerics for all Apple computers 
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Figure A- 1 

Roadmap fo the technical manuals 



To start finding oul 
about the Apple lies 



lo learn how 

fhe Apple JIGS works 

To start learning 



lo program the Apple IIGS 



To use the toolbox 



To use the development 
envlronmc 



To operai e on Hies 



To use C 



To use — 
assembly language 
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The introductory manuals 

These books are introductory manuals for developers, computer enthusiasts, and 
other Apple IIGS owners who need technical information. As introductory manuals, 
their purpose is to help the technical reader understand the features of the Apple IIGS, 
particularly the features that are different from other Apple computers. Having read 
the introductory manuals, the reader will refer to specific reference manuals for details 
about a particular aspect of the Apple IIGS. 



The technical introduction 

The Technical Introduction to the Apple lies is the first book in the suite of technical 
manuals about the Apple IIGS. It describes all aspects of the Apple IIGS, including its 
features and general design, the program environments, the toolbox, and the 
development environment. 

Where the Apple Has Owner's Guide is an introduction from the point of view of the 
user, die technical introduction manual describes the Apple IIGS from the point of 
view of the program. In other words, it describes the things the programmer has to 
consider while designing a program, such as the operating features the program uses 
and the environment in which the program runs. 



The programmer's introduction 

When you start writing Apple IIGS programs, the Programmer's Introduction to the 
Apple IIGS provides the concepts and guidelines you need. It is not a complete course 
in programming, only a starting point for programmers writing applications that use 
the Apple desktop interface (with windows, menus, and the mouse). It introduces ihe 
routines in the Apple IIGS Toolbox and the program environment they run under. It 
includes a sample event-driven program that demonstrates how a program uses the 
toolbox and the operating system, (An event-driven program waits in a loop uniil ii 
detects an event such as a dick of the mouse button.) 
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The machine reference manuals 

There are two reference manuals for Lhe machine itself: ihe Apple HGS Hardware 
Reference and lhe Apple IIGS Firmware Reference. These books coniain detailed 
specifications for people who want to know exactly whai's inside the machine. 



The hardware reference manual 

The Apple UGS Hardware Reference is required reading for hardware developers, 
and il will also be of interest to anyone else who wants to know how the machine works. 
Information for developers includes the mechanical and electrical specifications of all 
connectors, both internal and external. Information of general interest includes 
descriptions of the internal hardware, which provide a better understanding of the 
machine's features, 



The firmware reference manual 

The Apple lias Firmware Reference descrilies the programs and subroutines thai are 
stored in the machine's read-only memory (ROM), with two significant exceptions: 
Applesoft BASIC and the toolbox, which have their own manuals. The firmware 
reference manual includes information about interrupt routines and low-level I/O 
subroutines for the serial ports, the disk port, and the Apple DeskTop Bus in red are, 
which controls the keyboard and the mouse. The manual also describes the Monitor, a 
low-level programming and debugging aid for assembly-language programs. 



The toolbox reference manuals 

Like the Macintosh, the Apple I1C.S has a built-in toolbox. The Apple Has Toolbox 
Reference, Volume 1, introduces concepts and terminology and tells how to use some 
of the tools. The Apple ItGS Toolbox Reference, Volume 2, contains information 
about the rest of the tools and also tells how to write and install your own tool set.. 

Of course, you don't have to use the toolbox at all. If you only want to write simple 
programs thai don't use the mouse, or windows, or menus, or other parts of the 
desktop user interface, then you can get along without the toolbox. However, if you are 
developing an application that uses the desktop interface or if you want to use the Super 
Hi-Res graphics display, you'll find the toolbox to be Indispensable. 

In applications that use the desktop user interface, commands appear as options in 
pull-down menus, and material being worked on appears in rectangular areas of the 
screen called Windows. The user selects commands or other material by using the 
mouse to move a pointer around on the screen. 
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The programmer's workshop reference manual 

The Apple IIGS Programmer's Workshop (APW) is the development environment for 
the Apple EGS computer. APW is a set of programs that enables developers to create 
and debug application programs on the Apple IIGS. The Apple IIGS Programmer's 
Workshop Reference includes information about the APW Shell, Editor, Linker, 
Debugger^ and utility programs-, these are the parts of the workshop that all developers 
need, regardless of which programming language they use. 

The APW reference manual describes the way you use the workshop to create an 
application and includes examples and illustrations to show how this is done. In 
addition, this manual documents the APW Shell to provide the information necessary 
to write an APW utility or a language compiler for the workshop. 

Included in the APW reference manual are complete descriptions of two standard 
Apple IIG5 file formats: the text file format and the object module format. Hie text Ale 
format is used for all files written or read as "standard ASCII files" by Apple IIGS 
programs running under ProDOS 16, The object module format is used for the ouptut 
of all APW compilers and for all files loadable by the Apple IIGS System Loader. 



The programming-language reference manuals 

Apple currently provides a 65C816 assembler and a C compiler, Other compilers can 
be used with the workshop, provided that they follow the standards defined in the 
Apple IIGS Programmer's Workshop Reference. 

There is a separate reference manual for each programming language on the 
Apple IIGS. Each manual includes the specifications of the language and of the 
Apple IIGS libraries for the language, and describes how 10 use the assembler or 
compiler for that language. The manuals for the languages Apple provides arc the 
Apple IIGS Programmer's Workshop Assembler Reference and the Apple IIGS 
Programmer's Workshop C Reference. 

The Apple IIGS Programmer's Workshop Reference and the two programming- 
language manuals are available through the Apple Programmer's and Developer's 
Association. 
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The operating- system reference manuals 

There are vwo operating systenis that run on the Apple TIGS: ProDOS 16 and 
ProDOS 8. Each operating system is described in iis own manual: ProDOS 8 Technical 
Reference Manual and Apple IIGS ProDOS 16 Reference. ProDOS 16 uses the full 
power of the Apple TIGS, The ProDOS 16 manual describes its features and includes 
information about the System Loader, which works closely with ProDOS 16. If you are 
writing programs for Ihe Apple IIGS, whether as an application programmer or a 
system programmer, you are almost certain to need (he ProDOS 16 reference manual. 

ProDOS 8, previously just called ProDOS, is the standard opera ling system for most 
Apple II computers with 8-bit CPUs (Apple Tic, He, and 64K II Plus). U also runs on ihe 
Apple IIGS. As a developer of Apple IIGS programs, you need the ProDOS fi Technical 
Reference Manual only if you are developing programs to run on 8-bit Apple IPs as 
well as on the Apple COS. 



The all-Apple manuals 

In addition to the Apple IIGS manuals mentioned above, there are two manuals that 
apply to all Apple computers; Human Interface Guidelines: The Apple Desktop 
Interface and Apple Numerics Manual. If you develop programs for any Apple 
computer, you should know about those manuals. 

The Human Interface Guidelines manual describes Apple's standards for the desktop 
interface of any program that runs on an Apple computer. If you are writing a 
commercial application for the Apple IIgs, you should be fully familiar with the 
contents of this manual. 

The Apple Numerics Manual is the reference for the Standard Apple Numeric 
Environment (SANE™), a full implementation of the IEEE Standard for Binary 
Floating-Point Arithmetic (IEEE Std 754-1985). The functions of the Apple IIGS SANE 
tool sei match those of the Macintosh SANE package and of the 6502 assembly- 
language SANE software. If your application requires accurate or robust arithmetic, 
you'll probably want to use the SAIVE routines in the Apple IIGS. The Apple Has 
Toolbox Reference lefts how to use the SANE routines in your programs. The Apple 
Numerics Manual is the comprehensive reference for the SANE numerics routines. 
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Firmware ID Bytes 



The firmware ID bytes are used 10 identify the particular hardware system on which you 
are currently working. Table B-l lists the locations from which you can read ID 
information. Each system maintains three separate ID byte locations, as indicated in 
the table, If all three ID bytes match for a given system type, you will know that your 
software is running on that particular system. 



Table B-l 

ID Information locations 





Main ID 


Sub ID 1 


Sub ID2 


System 


(SFBE3) 


(FBCO) 


<$F6BF> 


Apple II 


S.i8 


$60 


S2F 


Apple n Plus 


SEA 


SEA 


$EA 


Apple lie 


$06 


$EA 


iC] 


Apple lie Plus 


$06 


SE0 


soo 


Apple 1IGS 


506 


$E0 


$00 


Apple He 


y:h 


$00 


$FF 


Apple nc Plus 


$06 


$00 


$00 



To distinguish the Apple IIGS from an Apple He Plus (the ID bytes arc identical), run 
the following short routine with the ROM enabled in the language card. 

■c - 1 as a starting point 
;RT5 for Apple II computers 
;prior to the Apple IIgs 

fit c - 1, then the system is an old Apple 31 
;If c = 0, then the system is a Apple IlGS or later and the 
registers are returned with the information in Table B-2. 



SEC 




JSB 


SPfiii 1 


BCS 


ITSAP?: 1 


BCC 


Apple LIgs 



Table B-2 

Register bit Information 



Baglster 


Bit 


Information 


A 


15-7 


Reserved 




6 


1, if system has a memory expansion slot 




5 


1, if system has an 1WM port 




4 


1, if system has a built-in clock 




3 


1, if system has Apple DeskTop Bus 




2 


1. if system has SGC 




1 


1, if system has external slots 







1, if system has internal ports 


y 


15-8 


Machine ID: 

00 Apple I1GS 

1-FF Future machines 



X 7-0 ROM version number 

The Y register contains the machine ID; the X register contains the ROM version 
number. 

♦ Note: If the ID call was made in emulation mode, only the low 8 bits of X, A and Y 
are returned correctly; however, the c bit is accurate. If the calt was made in native 
mode, the c bit as well as register information is accurate as shown in Table B-2 and 
is returned in full 16-bit native mode. The c bit is the carry bit in the processor status 
register. If the value returned in Y is $00, the value in A should be considered to be 
S7F. 
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Appendix C 



Firmware Entry Points 
in Bank $00 



Apple Computer, Inc. will maintain the entry points described within this document 
in any future Apple TIGS or Apple H-compatible machine thai Apple produces. No 
other entry points will be maintained Use of the entry points in this document will 
ensure compatibility with Apple Q*GS and future Apple TI-compatiblc machines. Note 
that these entry points are specific to Apple ITG5 and Apple IlGS-compatible machines 
and do not necessarily apply to Apple lie or Apple He machines. 

As an alternative to using these entry points, note that you can also use the 
Miscellaneous Tool Set FWENTRY firmware function. 

For all of ihe routines defined in this chapter, the following definitions apply: 
L A represents the lower 8 bits of die accumulator, 

□ B represents the upper 8 bits of the accumulator. 
Q X and Y represent 8-bit index registers. 

~i DRR represents the data bank register. 

□ K represents the program bank register. 
a P represents the processor status register. 

□ S represents the processor stack register. 

□ D represents the direct-page register. 
a e represents the emulation-mode bit, 

□ c represents the carry flag 

□ ? represents a value that is undefined 
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Warning 

For oil of the routines In this appendix, the following environment variables must 
be set with the values shown here: 

c The e bit must be set to 1 . 

□ The decimal mode must be set to 0. 

a K must be set to $00. 

d D must be set to S00O0. 

D OBR must be set to $00. 

Following are descriptions of the firmware routines supported as entry points in 
airren! and future models of the Apple II family, slatting with the Apple IlGS. 

SF800 PLOT Plot on the low-resolution screen only. 

PLOT puis a single block of the color value set by SETCOL on the 
low-resolution display scro i 

Input A = Block's vertical position (0-S2F) 

X- ? 

Y = Block's horizontal position (0-$27) 

Output Unchanged = X/Y/DBR/K/D/e 
Scrambled - A/B/P 



5F80E PLOT1 



Modify block on the low-resolution screen only. 



PLOT puts a single block of the color value set by SETCOL on the 
low-resolution display screen. The block is plotted at current settings of 
CBASL/GBASH with current COLOR and MASK settings 

Input A - ? 

X = ? 

Y = Block's horizontal position (0-S27) 

Output Unchanged = X/Y/DBR/K/D/e 
Scrambled *= A/B/P 
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$P819 
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HLINE Draw a horizontal tine of blocks on low-resolution screen 

only 

HLINE draws a horizontal line of blocks of the color sei by SETCOL on die 
low-resolution graphics display. 



Input 



Output 



$F828 VLINE 



A ■ Block's vertical position (0-$2F) 

X= ? 

Y = Block's leftmost horizontal position (0-$27) 

H2 = (Address = $2C); block's rightmost horizontal position 
(0-S27) 

Unchanged = X/DBR/K/D/e 
Scrambled - A/Y/B/P 

Draw a vertical line of blocks on the low-resolution screen 
only. 



VLINE draws a vertical line of blocks of the color set by SETCOL on the 
low-resotution display. 

Input A = Block's lop vertical position (0-52F) 

X ■ ? 
Y = Block's horizontal position (0-527) 

V2 = (Address = $2D>, block's bottom vertical position (0-$2F) 

Unchanged = X/DBR/K/D/e 
Scrambled - A/Y/B/P 

Clear the low-resolution screen only. 

CLRSCR clears the low-resolulion graphics display to black. If CLRSCR is 
called while the video display is in text mode, it fills the screen with inverse 
at sign (@) characters. 



Output 



SF832 CLRSCR 



Input 



A = ? 
X = ? 
Y = ? 



Output Unchanged = X/DBR/K/D/e 

Scrambled - A/Y/B/P 
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$F836 CLRTOP Clear ihe top 40 lines of the low-resolulion screen only, 

CLRTOP clears the lop 40 lines of ihe low-resolution graphics display On 
mixed mode, clears trie graphics portion of the screen to black). 



Output Unchanged - X/DBR/K/D/e 
Scrambled = A/Y/B/P 

SF847 GBASCALC Calculate base address For low- resolution graphics only. 

GBASCALC calculates the base address of the line on which a particular 
pixel is to be plotted. 

input A = Vertical line to find address for C0-S2F) 
X-? 
Y = ? 

Output Unchanged = X/Y/DBR/K/D/e 
Scrambled - B/P 
Special = A = GBASL 



SF85F 



NXTCOL 



Increment color by 3, 



NXTCOL adds 3 to the current color (sei by SETCOL) used for low-resolution 
graphics. 

Input A - ? 



Output Unchanged - X/Y/DBR/K/D/e 

Scrambled = B/P 

Special = A = New color in high or low nibble 
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$F&64 SETCOL 



Set low-resolution graphics color. 



f 



SETCOL sets the color used for plotting in low-resolution graphics. The 
colors are as follows: 

SO = Black 
$1 ■ Deep red 
$2 ^ Dark blue 
$3 = Purple 
$4 = Dark green 
$5 ■ Dark gray 

v - Medium blue 
$7 = Light blue 
$8 ■ Brown 
$9 = Orange 
$A = Light gray 
SB - Pink 
SC = Ught green 
$D = Yellow 
$E - Aquamarine 
SF = White 






Input 



Output 



$F871 5CRN 



A = Low nibble - new color to use-, high nibble doesn't matter 

X = ? 

Y-? 

Unchanged = X/Y/DBR/K/D/e 

Scrambled = B/P 

Special = A = New color in high or low nibble 

Read the low- resolution graphics screen only. 



SCRN returns the color value of a single block on the low-resolution graphics 
display. Call it with the vertical position of the block in the accumulator and 
horizontal position in the Y register 

Input A = Vertical line to find addr for (0-S2F) 

X- ? 
Y = ? 

Output Unchanged = X/Y/DBR/K/D/e 
Scrambled = B/P 
Special -A - Color of block specified in low nibble; 

high nibble - 






223 



Appendix C: Firmware Entry Points In Bonk $00 



$F88C INSDS1.2 Perform LDA (PCL,X>, then Fall into INSDS2. 

1NSDS1.2 gets ihe opcode to determine the instruction length of with an LDA 
CPCL,X) and falls into INSDS2. 

Input A = ? 

X - Offset into buffer at pointer PCL/PCH 
Y-? 

PCH = (Address $3B) high byte of buffer address to get opcode 
from in bank $00 

PCL = (Address = S3A) low byte of buffer address to gel opcode 

from in bank $00 

Output Unchanged «» DBR/K/D/e 

Scrambled = A/X/B/P 

Special = Y = 500 

LENGTH (address = $2F); contains instruction length 1 
of 6502 instructions or ■ $00 if noi a 6502 opcode 



$F88K INSDS2 



Calculate length of 6502 instruction. 

INSDS2 determines the length 1 of the 6502 instruction denoted by the 
opcode appearing in the A register. 

INSDS2 returns correct instruction length 1 of 6502 opcodes only. All non- 
6502 opcodes return a length of $00. For compatibility reasons, the BRK 
opo:u.k: re-.ums a k:ngih of $00, not S01 as DIN! would (BXpCOt tt K*. 

Input A ■ Opcode for which length is to be determined 

X = ? 
Y-? 

Output Unchanged = DBR/K/D/e 

Scrambled = A/X/B/P 

Special - Y - $00 

LENGTH (address = $2F); contains instruction length 1 
of 6502 instructions or = $00 if not a 6502 opcode 
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SF890 GET816LEN Calculate length of 65C816 instruction. 

GET816LKN determines the length of the 65816 instruction denoted by the 
opcode appearing in the A register. The BRK opcode returns a length of SOI 
as one would expect it to. 

Input A ■ Opcode for which length is lo be determined 

X - ? 

Y = ? 

Output Unchanged - DBR/K/D/e 
Scrambled = A/JC/B/P 
Sped a! - Y = $00 

LENGTH (address ■ $2F>, contains instruction length 1 

of 65C816 instructions 

SF8D0 INSTD5P Display disassembled instruction. 

INSTDSP disassembles and displays one instruction pointed lo by the 
program counter PCL/PCH (addresses S3A/53B) in bank SCO 

Input A = ? 
X= ? 

Y = ? 

Output Unchanged = DBK/K/D/e 
Scrambled = A/XA7B/P 



$F940 



PRNTYX 



Print contents of Y and X registers in hex format. 



PRNTYX prints the concerns of the Y and X registers as four-digit 
hexadecimal values. 

Input A - ? 

X = Low hex byte lo print 
Y = High hex byte to print 

Output Unchanged = X/Y/DBR/K/D/e 
Scrambled = A/1VP 



5-Pv'i] PRNTAX 



Print contents of A and X registers in hex format. 



PRNTYX prints the contents of the A and X registers as four-digit 
hexadecimal values. 

Input A - High hex byte to print 

X = Low hex byte to print 
Y = ? 

Output Unchanged - X/Y/DBR/K/D/c 
Scrambled = A/B/P 
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PRNTX 



Print contents of X register in hex format 



PRNTYX prints the contents of the X register as a two-digit hexadecimal 
value. 



Input 




A = ? 

X ■ Ilex byte to print 

Y 

Unchanged - XAVDBR/K/D/e 
Scrambled = A/B/P 



Print 3 spaces. 

PRBLNK outputs 3 blank spaces to the standard output device 

Input A - ? 
X = ? 

Y 

Unchanged - Y/DBR/K/D/e 
Scrambled - B/P 
Special = X = $00 

A - $A0 Cspace ASCII code) 

Print X number of blank spaces. 

PRBL2 outputs from 1 to 256 blanks to the standard output device 

A = ? 

X - Number of blanks to print (500 - 256 blanks} 

Y-? 

Unchanged - Y/DBR/K/LVc 
Scrambled = B/P 
Special = X = $00 

A - SAO Cspace ASCII code) 



Appendix c: Hrmware fcntry Points In Bank SO0 



^m 



231 



SF953 PCADJ 



Adjust Monitor program counter. 



PCADJ increments the program counter by 1, 2, 3, or 4, depending on the 
LENGTH (address 52F) byte; - add 1 byte, 1 ■ add 2 bytes, 2 - add 3 bytes, 
3 = add 4 bytes. 

Note: PCL/'PCH (addresses fc3A/.$3B) are not changed by this call. The 
A/Y registers contained the new program counter at the end of this call. 

Input A ■ ? 

X = ? 

Y ■' 

PCL = (Address $3A) program counter low byte 

PCH = (Address $3B) program counter high byte 

LENGTH = (Address $2F> length 1 to add to program counter 

Output Unchanged - BBR/K/D/e 

Scrambled = X/B/P 
Special ■ A ■ New PCL 

Y = New PCH 

PCL/PCH not changed 

SK962 TEXT2COPY Enable or Disable text Page 2 software -shadowing. 

TEXT2GOPY toggles ihe text Page I software-shadowing function on and 

off. The first access to TEXT2COPY enables shadowing, and the next access 
disables shadowing. When TEXT2COPY is enabled, a heartbeat task is 
enabled that, on every VBL, copies the information from bank $00 
locations $04QQ-$07FF to bank $E0 locations S0400-S07FF. It then enables 
VBL interrupts. VBL interrupts remain on until Control Reset is pressed or 
until the system is restarted TE3O2C0PY can disable [be copy function, 
but cannot disable VBL interrupts once they are enabled. 

Input A = ? 

X = ? 
Y-? 

Output Unchanged = DBR/K/D/e 
Scrambled - A/X/Y/B/P 
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SFA40 OLDIRQ 



Go lo emulation-mode interrupt-handling routines. 



Jumps to the interrupt-handting routines that handle emulation-mode liRKs 
and IRQs. AJJ registers arc restored after the application performs an RTI at 
the end of its installed interrupt routines. Location $45 is not destroyed as In 
the Apple II, Apple II Plus, and original Apple lie computers. 

Input A * ? 

X = ? 
Y = ? 

Output Unchanged - A/X/Y/DBR/P/B/K/D/e 
Scrambled = Nothing 



SFA-iC BREAK 



Old 6502 break handler. 



BREAK saves the 6502 registers and the program counter and then jumps 
indirectly through the user hooks at $03rH)/$O3Fl. Note lhat this call affects 
the 6502 registers, not the 65C816 registers. This entry point is obsolete 
except in very rare circumstances. 

Input A = Assumes A was stored at address $45 

X= ? 
Y-? 

Output Unchanged = DBR/K/D/e 

Special = A5H (address $45) = A value 
XREG (address $46) « X value 
YREG (address $47) = Y value 
STATUS Caddress S48) - P value 
SPNT Caddress $49) = S stack 
Pointer value 






SFA59 OLDBRK 



New 65C816 break handler. 



OLDBRK prints the address of the BRK instruction, disassembles the BRK 
instruction, and prints the contents of the 65C816 registers and memory 
configuration at the time the BRK instruction was executed. 

Input All 65C816 registers and memory configuration saved by 

interrupt handler 

Output Returns to Monitor after displaying information 
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JFA62 RESET 



Hardware resei handler. 



RESET sets up all necessary warm-start parameters for the Apple IIgs. It is 
called by the 65C816 reset vector stored in ROM in locations SFFFC/5FFFD. 
If normal warm start occurs, it then exits through user vectors at 
$03F2/503F3- if cold start occurs, it then exits by attempting to start a startup 
device such as a disk drive or AppleTalk, depending °n Control Panel 
sellings. Ufa program JMPs here, it must enter in emulation mode with the 
direct-page register set to $0000, the data bank register set to $00, and the 
program bank register set to $00, or RESET will not work. 

Input K/DBR/D/e - $00 

Output Doesn't return to calling program 



SFAA6 PWRUP 



System cold-start routine. 



PWRUP performs a partial system reset and then attempts to start the system 
via a disk drive or AppleTalk. PWRUP also zeros out memory in bank 00 
from address $0800-$BFEF. If a program JMPs here, it must enter in 
emulation mode, with the direct-page register set lo 50000, the data bank 
register set to $00, and the program bank register set to $00, or RESET will 
not work. If no startup device is available, the message Check startup 
Device appears on the screen. 



Input 



K/DBR/D/e = $00 



Output Doesn't return to calling program 



SFABA SLOOP 



Disk controller slot search loop. 



SLOOP is the disk controller search loop. It searches for a disk controller 
beginning at the peripheral ROM space (if RAM disk, ROM disk, or 
AppleTalk has not been selected via the Control Panel as the startup 
device) pointed to by LOCO and LOCI (addresses $00/$01). If a startup 
device is found, it JMPs to that card's ROM space. If no startup device is 
found, the message Check Startup Device appears on the screen. If 
RAM disk or ROM disk has been selected, then the firmware JMPs to the 
SmartPort code that handles those startup devices. If slot 7 was selected and 
AppleTalk is enabled in port 7, the firmware JMPs to the AppleTalk boot 
code in slot 7. 

Input A - ? 

X = ? 

Y - ? 

LOCO - (Address $00)-, must be $00, or startup will not occur 
LOCI = (Address $01); contains $Cn„ where n = next slot 
number to test for a startup device 

Output Doesn't return to calling program 



234 



Appendix C: Firmware Entry Points In Bank $00 





$FAD7 


REGDSP Display contents of registers, 

REGDSP displays all 65C816 register contents stored by the Firmware and 
Apple 1IGS memory-stale information, including shadowing and system 
speed. Displayed values include A/X/Y/K/DBR/S/D/P/M/Q/m/x/e/L, 
A/X/Y/5 are always saved and displayed as 16-bit values, even if emulation 
mode or 8-bil native mode is selected. 

Input A - ? 
X = ? 
Y*? 

Output Unchanged ■ DBR/K/D/e 
Scrambled - A/X/Y/B/P 




SFB19 


RTBL Register names table for 6502 registers only. 

This is not a callable routine. It is a fixed ASCII string. The fixed string is 
'AXYPS'. Some routines require this string here, or they will not execute 
properly. The most significant bit of each ASCII character is set to 1. 

Input No input (not a callable routine) 

Output No output (not a callable routine) 




SFB1E 


PREAD Read a hand controller, 

PREAD returns a number that represents the position of the specified hand 
controller. 

Input A = ? 

X - 0, 1, 2, or 3 only = Paddle to read 
Y = ? 

Output Unchanged = X/DBR/K/D/e 
Scrambled - A/B/P 
Special *» Y ■ Paddle count 




SFB21 


PREAD4 Check timeout paddle-, then read the hand controller. 

PREAD4 verifies that the paddle (hand controller) is in timeout mode and 

then reads i he paddle 'he same as PREAD does, returning a number thil 
represents the position of the specified hand controller. 

Input A = ? 

X = 0, 1, 2, or 3 only ■ Paddle to read 
Y = ? 

Output Unchanged = X/DBR/K/D/e 
Scrambled = A/B/P 
Special ■ Y ■ Paddle count 
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SFB2F I NIT Initialize text screen, 

INJ1T sets up the screen for full window display and icxl Page 1. 
Input 



Output 



$FB39 SETTXT 



A = ? 
X = ? 

Y -? 

Unchanged = DBR/K/D/e 
Scrambled - X/Y/B/P 
Special - A » BASL 

Set text mode. 



SETTXT sets screen for full text window, but docs not force text Page 1, 



Input 



Output 



SFB40 SETGR 



A - ? 
X = ? 
Y = ? 

Unchanged = DBR/K7D/e 
Scrambled - X/Y/B/P 
Special = A = BASL 

Set graphics mode_ 



SETGR sets screen for mixed graphics mode and clears the graphics portion 
of the screen. It then sets the top of the window to line 20 for four lines of text 
space below ihe graphics screen. 



Input 



Output 



$FB4B SETWND 



A = ? 
X-? 
Y = ? 

Unchanged - DBR/K/D/e 
Scrambled = X/Y/B/P 
Special - A - BASL 

Set texi window si2e. 
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SETWND sets window to the following: 

WNDLFT (address = $20) = S00 

WNDWDTH (address - S21) = $28/$50 (40/80 columns) 

D'I'OP (address 522) = A on entry 
WNDBTM (address $23) = SIS 

Input A ■ New WNDTOP 

X = ? 
Y = > 

Output Unchanged - X/DBR/K/D/e 
Scrambled = Y/B/P 
Special = A = BASL 
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> Fli 5 1 SE TW n D 2 Set text window width and bot torn size , 

SETWND2 sets window- to the following: 

WNDWDTil (address - $21) - S28/$50 (40/80 columns) 
WNDBTM (address $23) - $18 

Input A = ? 

X = ? 
Y-? 

Output Unchanged = X/DBR/K/D/e 
Scrambled = Y/B/P 

Special - A - BASL 



SFB5B TABV 



Vertical lab. 



TABV stores the value in A in CV (address $25) and then calculates a new 
base address for storing data to the screen. 

Input A = New vertical position (line number) 

X* ? 

Y = ? 

Output Unchanged = X/DBR/K/D/e 
Scrambled - Y/B/P 
Special ■» A - BASL 

$FB60 APPLEII Clears screen and displays Apple I1GS logo. 

APPLEII clears the screen and displays the startup ASCII string 'Apple AGS' 
on the first line of the screen. 

Input A - ? 

X = ? 

Y = ' 

Output Unchanged = X/DBR/K/D/e 
Scrambled - A/Y/B/P 

SFB6F SETFWRC Create power-up byte. 

SETPWRC calculates the "funny" complement of the high byte of the RESET 
vector and stores it at PWREDUP (address S03F4). 

Input A - ? 
X = ? 

Y = ? 

Output Unchanged - X/Y/DBR/K/D/e 
Scrambled = B/P 

Special = A = PWREDUP 
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SFB78 VI D WAIT Check for a pause (Conuol-S) request. 

VIDWAIT checks the keyboard Tor a Control-S if it is called with an S8D 
(carriage return) in the accumulator, If a Control-S is found, the system falls 
through to KBDWAtT. If it is not. control is sent to VIDOUT, where the 
character is printed and the cursor advanced. 

Input A = Output character 

X = ? 

Y = ? 

Output Unchanged - X/DBR/K/D/e 
Scrambled = A/Y/B/P 

SFBag KBDWAJT Wait lor a keypress. 

KBDWAJT waits for a keypress. The keyboard is cleared (unless the keypress 
is a Control-O. and then control is sent to VIDOUT, where the character is 
primed and the cursoi advanced 

Input A = ? 

X = ? 

Y- ? 

Output Unchanged = X/DBR/K/D/e 
Scrambled = A/Y/B/P 

5FBB3 VERSION One of the monitor ROM's main identification bytes. 

This is not a callable routine. It is a fixed hex value The fixed value is $06. 
This is the identification byte dial indicates whether this is an Apple He or a 
later system. This byte is the same in the Apple He, the enhanced Apple lie, 
the Apple lie. the enhanced Apple He, and the Apple IlGS. 

Input No input (not a callable routine) 

Output No output (not a callable routine) 

SFBBF ZIDBYTE2 One of the monitor ROM's main identification bytes. 

This is not a callable routine. It is a fixed hex value. The fixed value is $00, 
This is the identification byte that indicates this is an enhanced Apple He or 
■i later system. 

Input No input (not a callable routine) 

Output No output (not a callable routine) 
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SFBCO ZIDBYTE One of the Monitor ROM's main identification bytes. 

This is not a callable routine. It is a fixed hex value. The fixed value is SEO. 
This is die identification byte that indicates this is an enhanced Apple lie or 
a later system. 



Input 
Output 

SFBC1 BASCALC 



No input (not a callable routine) 
No output (not a callable routine) 

Text basC'address calculator. 



BASCALC calculates the base address of the line for the next text character 
on the 40-column screen. The values calculated are stored at BASL/BA5II 
(addresses $0028/50029). 



Input 



Output 



SFBDD BELLI 



A = tine number to calculate base for 
X-? 

Y = ? 

Unchanged - X/Y/DBR/K/D/e 
Scrambled = B/P 
Special = A = BASL 

Generate user-selected bell tone. 



BELLI generates the user-selected Cvia the Control Panel) bell tone. There 
is a delay prior to the tone being generated to prevent rapid calls to BELLI 
from causing distorted bell sounds. 



Input 



Output 



SFBE2 BELLI. 2 



A-? 
X = ? 
Y-? 

Unchanged = X/DBR/K/D/c 
Scrambled = A/B/P 
Special - Y - $00 

Generate user-setecled bell tone. 



BELLI. 2 generates the user-selected (via the Control Panel) bell tone. 
There is a delay prior to the tone being generated to prevent rapid calls to 
BELLI. 2 from causing distorted bell sounds. 

Input A - ? 

X = ? 
Y = ? 

Output Unchanged = X/DBR/K/D/e 
Scrambled = A/B/P 
Special = Y = S00 
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$FBE4 



BELL2 



Generate user-selected bell tone. 



BELL2 generates the user-selected (via the Control Panel) bell lone. There 
is a delay prior lo the tone being generated to prevent rapid calls to BELL2 
from causing distorted bell sounds. 

Input A = ? 

X- ? 

Y = ? 

Output Unchanged = X/DBR/K/D/e 
Scrambled = A/B/P 
Special = Y = 



SFBFO STORADV Place a printable character on the screen, 

STORADV stores the value in the accumulator ai the next position in the lexl 
buffer (screen location) and advances lo die next screen location position. 

Input A = Character to display in line 

X ■ ? 
Y-? 

Output Unchanged = X/DBR/K/D/e 
Scrambled - A/Y/B/P 



SFBF4 ADVANCE Increment the cursor position. 

ADVANCE advances the cursor by one position. If the cursor is at the 
window limit, this call issues a carriage return to go to the next line on the 
screen. 



Input 



Output 



SFBFD VIDOUT 






A = ? 
X- ? 

Y = ? 

Unchanged = X/DBR/K/D/e 
Scrambled = A/Y/B/P 

Place a character on the screen, 






VIDOUT sends printable characters 10 STORADV. Return, line feed, 
forward, reverse space, and so on are sent to the vector of appropriate 
special routines. 

Input A = Character to output 

X- ? 
Y = ? 

Output Unchanged - X/DBR/K/D/e 
Scrambled = Y/B/P 

Special = A = Output character 
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SFC10 BS 



Backspace. 

lis d 4 'i.:i\-mt'nL<i Lhc Cursor one position If the CtUSOI tS :il Ihe beginning of 
the window,, the horizontal cursor position is set to the right edge of the 
window, and the routine goes to the UP subroutine. 

Input A = ? 

X= ? 

Y = > 

Output Unchanged = X/DBR/K/D/e 
Scrambled * A/Y/B/P 



$FC1A UP 



Move up a line. 



UP decrements the cursor vertical location by one line unless the cursor is 
currently on the first line. 



Input 



Output 



$FC22 VTAB 



A = ? 

X = ? 

Y = ? 

Unchanged - X/Y/DBR/K/D/e 
Scrambled = A/B/P 

Vertical lab. 



VTAB loads the value at CV (address $25) into the accumulator and goes to 
VTABZ. 



Input 



Output 



SFC24 VTABZ 



A = ? 
X-? 

Y = ? 

Unchanged = X/Y/DBR/K/D/e 
Scrambled - B/P 
Special = A - BASL 

BASL/BASH (addresses S28/S29) = New base address 

Vertical tab (alternate enLry). 



VTABZ uses the value in the accumulator to update the base address used for 
storing values in the text screen buffer. 

Input A = Line to calculate base address for 
X = ? 
Y-? 

Output Unchanged - X/Y/DBR/K/D/e 
Scrambled = B/P 
Special - A « BASL 

BASL/BASH (addresses S28/S29) = New base address 
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SFC42 CLREOP Clear to end of page. 

CLREOP clears the text window from the cursor position to the bottom of the 

window. 

Input A = ? 

X = ? 

Y-? 

Output Unchanged ■ X/DBR/K/D/e 
Scrambled = A/Y/B/P 

$FC58 HOME Hora: cursor and (iv.u \c ,.r,d r>t pag<: 

HOME moves ihe cursor to the top of screen column and then clears from 
there to the bottom of the screen window. 

Input A = ? 

X ? 

Y- ? 

Output Unchanged = X/DBR/K/D/e 
Scrambled - A/Y/B/P 

SFC62 CR Begin a new line. 

CR sets the cursor horizontal position ai the left edge of the window and then 
goes to LF to move to the next line on Ihe screen, 

Input A = ? 

X - ? 
Y = ? 

Output Unchanged = X/DBR/K/D/e 
Scrambled = A/Y/B/P 

$FC66 LF Line feed. 

LF increments the vertical position of the cursor, If the cursor vertical 
position is not past the bottom line, the base address is updated; otherwi.se, 
the routine goes to SCROLL to scroll the screen. 

Input A - ? 

X= ? 
Y-? 

Output Unchanged = X/DBR/K/D/e 
Scrambled = A/Y/B/P 
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$FC70 SCROLL 



Scroll the screen up one line. 

SCROLL moves all characters up one line within the current text window. 
The cursor postion is maintained. 

Input A = ? 
X- ? 
Y = ? 

Output Unchanged = X/DBR/K/D/e 
Scrambled * A/Y/B/P 



$FC9C CLREOL 



Clear to end of line. 



CLREOL dears a text line from the cursor position to the right edge of the 
window. 



Input 



Output 



A - ? 
X = ? 
Y = ? 

Unchanged = X/DBR/K/D/e 
Scrambled = A/Y/B/P 



SFC9E CLREOLZ Clear to end of line. 

CLREOLZ dears from Y on the current line to the right edge of die text 
window. 



Input 



Output 



A-? 
X = ? 



Y - Horizontal position to start clearing from 

Unhanged = X/DBR/K/D/e 
Scrambled = A/Y/B/P 



SFCA8 WAIT 



Delay loop (system-speed independent)- 



WAIT delays for a specific amount of lime and then returns to the program 
that called it, 'line length of the delay is specified by the contents of the 
accumulator. With A the contents of the accumulator, the delay is 
1/2C26+27A+5AA2)*14/I4.318i8 microseconds. WAIT should be used as a 
minimum delay lime, nol as (he absolute delay time, 

Input A - ? 
x = ? 

Y = ? 

Output Unchanged = X/Y/DBR/K 
Scrambled - B/P 
Special = A = $00 
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SFCB4 NXTA4 Increment pointer at A41/A4H (addresses $42/$43>. 

NXTA4 increments the 1 6-bit pointer at A4L/A4H and then goes to NXTA1. 

Input A = ? 
X = ? 
Y = ? 

Output Unchanged = X/Y/DBR/K/D/e 
Scrambled - A/B/P 



: -i I 15 A NXTA1 



Compare A1L/A1H (addresses S3C/S3D) with A2L/A2H 
(addresses S3E/S3F) and then increment A1L/AIH. 



NXTA1 performs a l6-bil comparison of A1L/A1H with A2L/A2H and 
increments the 16-bit pointer A1L/A1H. 

Input A = ? 
X-? 

Y=? 

Output Unchanged = X/Y/DBR/K/D/e 
Scrambled = A/B/P 



$FCC9 HEADR 



Write a header to cassette tape (obsolete). 



HEADR is an obsolete entry point for the Apple IIGS. It does nothing except 
perform an RTS back to the calling routine. 



Input 

Output 
SFDOC RDKEY 



A-? 
X = ? 
Y = ? 

Unchanged = A/X/Y/P/B/DBR/K/D/e 

Get an input character and display old inverse flashing 
cursor. 






RDKEY is a character-input subroutine. It places the old Apple II inverse 
character flashing cursor on the display at the current cursor position and 
jumps to subroutine SFD10. 

Input A - ? 
X = ? 

Y = ? 

Output Unchanged = X/DBK/K/D/e 
Scrambled = Y/B/P 
Special - A - Key pressed (entered character) 



?u 
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$FD10 FD10 



Get an input character and don't display inverse flashing 
character cursor. 



FD10 is a character-Input subroutine. It jumps to the subroutine whose 
address is stored in KSWL/KSWH (addresses S38/S39), usually the standard 
input subroutine KEYIN, which displays the normal cursor and returns with a 
character in the accumulator. SFD10 returns only after a key has been 
pressed or an input character has been placed in ihe accumulator. 

Input A = ? 

X-? 
Y = ? 



Output 



SFD18 RDKEY1 



Unchanged - X/DBR/K/D/c 

Scrambled - Y/B/P 

Special = A = Key pressed (entered character) 

Get an input character. 



RDKEY1 jumps to the subroutine whose address is stored in KSWL/KSWH 
(addresses $38/539), usually the standard input subroutine KEYIN, which 
returns with a character in the accumulator. RDKEY1 returns only after a key 
has been pressed or an input character has been placed in the accumulator. 

Input A = ? 
X = ? 
Y = ? 



Output 



SFD1B KEYIN 



Unchanged = X/DBR/K/D/e 

Scrambled = Y/B/P 

Special - A = Key pressed (entered character) 

Read the keyboard. 



KEYIN is a keyboard-input subroutine. Il tests the Event Manager to see if it 
is active, If it is active, KEYIN reads the key pressed from the Event 
Manager; otherwise, it reads the Apple keyboard directly. In any case, it 
randomizes the random-number seed RNDL/RNDH (addresses 54E/S4F). 
When a key is pressed, KEYIN removes the cursor from the display and 
returns with the keycode in the accumulator. 

Input A = Character below cursor 

X = ? 

Y = > 

Output Unchanged - X/DBR/K/D/e 
Scrambled = Y/B/P 
Special • A = Key pressed (entered character) 
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SFD35 RDCHAR 



Gel an input character and process escape codes. 

RDKEY is a character-input subroutine; it also interprets the standard 
Apple escape sequences. It places an appropriate cursor on the display aL 
the cursor position and jumps to the subroutine whose address is store 
KSWL/KSWH (addresses 338/539), usually the standard input subroutine 
KEY1N, which returns with a character in the accumulator. RDCHAR returns 
only after a non-e escape-sequence key has been pressed or an input 
character has been placed in the accumulator. 

Input A = ? 

X = ? 

Y = ? 

Output Unchanged = X/DBR/K 
Scrambled - Y/B/P 
Special = A = Key pressed (entered character) 



$FD67 getlnz 



Get an input line after issuing a carriage return. 

GETLNZ is an alternate entry point for GETLM that sends a carriage return to 
the standard output and Lhen continues in GETLN. The calling program 
must call GETLN with the prompt character at PROMPT (address 333). 



Input 



Output 



SFD6A GETLN 



A = ? 
X = ? 
Y-? 

PROMPT = (Address 533) - Prompt character 

Unchanged = DBR/K/D/e 
Scrambled = A/Y 

Special = $200-$2xx contains inpui line 
X - Length of input line 

Get an input line with a prompt. 



GETLN is a standard input subroutine for entire lines of characters. The 
calling program must call GETLN with the prompt character at PROMPT 
(address $33). 



Input 



Output 



A = ? 
X-? 

Y = ? 

PROMPT = (Address $33) 



Prompt character 



i >. changed = DBR/K/D/e 

Scrambled s a/Y/B/P 

Special = $2QG-$2xx contains input line 
X - Length of input line 
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$FD6C GETLNO 



Gel an input line with a prompt (alternate entry), 






GETLNO outputs the contents of the accumulator as the prompt. If the user 
cancels the input line with Control -X or by entering too many backspaces, 
the contents of PROMPT (address $33) will be issued as the prompt when it 
gels another line. 



Input 



Output 



SFD6F GETLN1 



A ■ prompt character 

X-? 

Y = ? 

PROMPT = (Address $33) = Prompt character 

Unchanged - DBR/K/D/e 

Scrambled = A/Y/D/P 
Special = $200— S2xx contain,? input line 
X = length of input line 

Get an input line with no prompt (alternate entry). 



GETLNi is in alternate entry petal Eoi - IE 1 N thai does n x ssue a prompt 

before it accepts the input line. If the user cancel? the input line with 
Control-X or by entering too many backspaces, the contents of PROM I*' I 
(address $33) will be issued as the prompt when it gets another line. 

Input A = ? 

X = ? 

Y = ? 



Output 



SFD8B CRQUT1 



PROMPT - (Address $33) = Prompt character 

Unchanged = DBR/K/D/e 
Scrambled - A/Y/B/P 
Special = $200-$2xx contains input line 
X - Length of input line 

Clear to end on line; then issue a carriage return. 






CROUT1 clears ihe current line from the current cursor position lo Ihe right 
edge of the texi window. It then goes to CROUT to issue a carriage return, 



Input 



Output 



A = ? 
X = ? 

Y = ? 

Unchanged = X/DBR/K/D/e 

Scrambled = Y/B/P 

Special - A - $8D (carriage return) 
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SFD8E CKOUT 



Issue a carriage relurn. 

CROUT issues a carriage return lo ihe output device pointed to by 
CSWL/CSWH (addresses $36/537), 

Input A - ? 
X = ? 
Y = ? 



Output 



$FD92 PRA1 



Unchanged - X/Y/DBR/K/D/e 

Scrambled = B/P 

Special = A - S8D (carriage return) 

Print a carriage return and A1L/A1H (addresses $3C/$3D)- 

PRA1 sends a carriage return character ($8D) to the current output device, 
Followed by the contents of the 16-bit pointer A1L/A1H (addresses 
($3C/53D) in hex, Followed by a colon (:), 

Input A = ? 
X = ? 

Y = ? 

Output Unchanged- DBR/K/D/e 
Scrambled = X/B/P 
Special - A - SBA (colon) 
Y=$00 



SFDDA PRBYTE 



Print a hexadecimal byte. 



PRBYTE outputs the contents of the accumulator in hexadecimal formal to 
the current output device. 

Input A = Hex byte to print 
X«? 
Y = ? 

Output Unchanged = X/Y/DBR/K/D/e 
Scrambled = A/B/P 



SFDE3 PRHEX 



Print a hexadecimal digit. 



PRHEX outputs the lower nibble of the accumulator as a single hexadecimal 
digit to the current outpul device. 

Input A = Lower rubble is digit to output 
X - ? 
Y = ? 

Output Unchanged - X/Y/DBR/K/D/e 
Scrambled = A/B/P 
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SFDED COUT 



Output a character. 



COUT calls the current output subroutine. The character to output should be 
in the accumulator. COUT calls the subroutine whose address is stored in 
CSWL/CSWH (addresses $36/$37), which is usually the standard character- 
output routine COUTL 



Input 



Output 



SFDFO COUTl 



A = Character to print 
X = ? 

Y = ? 

Unchanged = A/X/Y/DBR/K/D/e 
Scrambled - B/P 



Output a character to the screen. 

COUTl displays the character in the accumulator on the Apple screen at the 
current output cursor position and advances the output cursor. It places the 
character using the settings of the normal/inverse location TNVFLG (address 
$32). It handles the control characters for return (58D), line feed CS8C), 
Backspace/Left Arrow ($88), Right Arrow ($95), and bell ($87) and the 
Change Cursor command (Control-* = S9E) 

Input A = Character to print 

X-? 
Y = ? 

Output Unchanged - A/X/Y/DBR/K/D/e 
Scrambled = B/P 



$FDF6 coutz 



Output a character to the screen without masking it with the 
inverse flag, 

COUTZ outputs the character in the accumulator without masking it with the 
inverse flag INVFLG (address $32) Output goes to the screen. 

Input A = Character to print 

X = ? 

Y = ? 

Output Unchanged = A/X/Y/DBR/K/D/e 
Scrambled = B/P 
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$FEIF IDROUTINE Returns identification information about the system. 

IDROUTLNE is called with c (carry) sei. If it returns with c (carry) dear, then 
the system Is an Apple II GS or a later system, and the registers A/X/Y 
contain identification information about the system. 

Input A = ? 
X- ? 

Y ? 

Output Unchanged = DBR/K/D/e 
Scrambled = B/P 
Special - c Ccarry) = if Apple IIGS or later. If c = 0, then A/X/Y 

contain identification information. If c - 1. then 

A/X/Y are unchanged, 



SFE2C MOVE 



Original Monitor Move routine. 

MOVE copies the contents of memory from one range of locations to 
another, This subroutine is not the same as the Monitor Move (M) 
command. The destination address must be in A4L/A4H (addresses 
$42/$43), the starling source address in A1L/A1H (addresses $3C/$3D), 
and the ending source address in A2L/A2H (addresses 53E/S3F) when 
MOVE is called. Y must contain the starling offset inlo the 
source/destination buffers. 



Input 



Output 



A = ? 
X-? 
Y = Starting offset into source/destination buffers (normally 

$00) 
A1L/A1H = (Addresses S3C/S3D) - Stan of source buffer 
A2L/A2H = (Addresses $3E/$3F) = End of source buffer 
A4L/A4H - (Addresses $4 2/$ 4 3) = Start of destination 
buffer 

Unchanged = X'Y/DBR/K/D/e 

Scrambled = A/B/P 

Special - A1L/A1H = (Addresses S3C/S3D) = End of source 

buffer + 1 

A2L/A2H = (Addresses S3E/S3F) - End of source 

buffer 

A4L/A4H = (Addresses $42/$43) = End of destination 

buffer + 1 



SPE5E -LIST" 



Old list entry point (noi supported under Apple IIGS). 
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5FE80 


SETINV 


Set inverse text mode. 




SETLNV sets INVFLG (address $32) so that subsequent text output to the 
screen will appear in inverse mode. 




Input 


A = ? 
X-? 
Y-? 




Output 


Unchanged = A/X/DBR/K/D/e 
Scrambled = Y/B/P 
Special - INVFLG (address 532) - $3F 
Y = S3F 


SFE84 


SETNORM 


Set normal text mode. 




SETNORM sets INVFLG (address $32) so that subsequent text output to the 
screen will appear in normal mode. 




Input 


A = ? 
X -? 
Y = ? 




Output 


Unchanged - A/X/DBR/K/D/e 
Scrambled = Y/B/P 
Special = INVFLG (address $32) - $FF 
Y = SFF 


SFE89 


SETKBD 


Reset input to keyboard. 




SETKBD resets inpul hooks KSWL/KSWH (addresses $38/$39) to point to 
the keyboard. 




Input 


A - ? 
X-? 
Y = > 




Output 


Unchanged = DBR/K/D/e 
Scrambled = A/X/Y/B/P 


$FE8B 


INPORT 


Reset input to a slot 




IMPORT resets input hooks KSWl/KSWH (addresses S3a'$39) to point to the 
ROM space reserved for a peripheral card (or port) in the slot (or port) 
designated by the value in the accumulator. 




Input 


A - Slot number to set hooks to 

X = ? 

Y-? 






.. 


Output 


Unchanged = DBR/K/D/e 
Scrambled - A/X/Y/B/P 

Appendix C. Firmware Entry Points In Bank $00 251 



SFE93 SETVID 



Reset output to screen 

SETVTD resets output hooks CSWL/CSWH (addresses $36/$37) lo ihe screen 
display routines. 



Input 



A = ? 

X = ? 

Y = ? 



Output Unchanged - DBR/K/D/e 
Scrambled - A/X/Y/B/P 



SFE95 OtJTPORT 



Reset output lo a slot 

OUTPORT resets output hooks CSWL/CSWH (addresses S36/S37) to point to 
the ROM space reserved for a peripheral card (or port) in the slot (or port) 
designated by the value in the accumulator. 

Input A = Slot number to reset hooks to 

X = ? 
Y-? 

Output Unchanged « DBR/K/D/e 
Scrambled = A/X/Y/B/P 



$FEB6 GO 



Original Apple II Go entry point. 



GO begins execution of the code pointed to by A1L/A2L (addresses 
S3C/$3D). 

Input A = ? 

X = SOI (required) 

Y-? 

A1L/A1H (addresses $3C/$3D) = Start address of program to 

run 
A5H (address $45) - A value to set up before running program 
XREG (address $46) = X value to set up before running program 
YREG (address $47) = Y value to set up before running program 
STATUS (address 548) = F status to set up before running 

program 

Output Unchanged - DBR/K/D/e 
Scrambled = A/X/Y/B/P 
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SFECD 



JFEFD 



SFF2D 



$FF3A 







WRITE 


Write a record to cassette tape (obsolete). 


WRITE is an obsolete entry point under Apple 1IGS, H does nothing except 
perform an RTS back to the calling routine. 


Input 


A- ? 
X = ? 
Y-? 


Output 


Unchanged = A/X/Y/P/BDBR/K/D/e 


READ 


Read data from a cassette tape (obsolete). 


READ is an obsolete entry point under Apple HGS. Ii does nothing except 
perform an RTS back to the calling routine. 


Input 


A = ? 
X -? 
Y = ? 


Output 


Unchanged = A/X/Y/P/B/DBR/K/D/e 


PRFHR 


Print ERR on output device. 


PR.ERR sends ERR to the output device and goes to BELL. 


Input 


A = ? 
X-? 
Y = ? 


Output 


Unchanged = X/Y/DBR/K/D/e 

Scrambled - B/P 

Special = A = S87 (bell character) 


BELL 


Send a bell character to the output device. 


BELL writes a bell (Control- G) character to the current output device 


Input 


A = ? 
X = ? 
Y -? 


Output 


Unchanged = X/Y/DBR/K/D/e 

Scrambled = B/P 

Special = A = $87 (bell character) 
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$FF3F 



RESTORE Restore A/X/Y/P registers. 

Restore 6502 register information from locations S45- 



Input 



Output 



SFF-iA SAVE 



A = ? 
X-? 

Y=? 

ASH (address $45) = New value for A 
XREG (address $46) = New value for X 
YREG (address $47) * New value for Y 
STATUS (address $48) = New value for P 

Unchanged = DBR/K/D/c 
Scrambled = B 
Special = A = New value 

X - New value 

Y = New value 

P = New value 

Save A/X/Y/P/S registers and clear decimal mode. 



SAVE saves 6502 register information in locations $45-349 and clears 
decimal mode- 



Input 



Output 



SFF58 IORTS 



A = ? 

X- ? 

Y = ? 

Unchanged - Y/DBR/K/D/e 

Scrambled = A/X/B/P 

Special = A5H (address $45) = Value of A 
XREG (address $46) = Value of X 
YREG (address $47) - Value of Y 
STATUS (address $48) = Value of P 
SPNT (address S49) = Value of stack pointer 2 
Decimal mode is cleared. 

Known RTS instruction. 



IORTS is used by peripheral cards to determine which slot a card is in, This 
RTS is fixed and will never be changed. 

Input A = ? 

X = ? 
Y-? 

Output Unchanged = A/X/Y/DBR/K/D/e 
Scrambled = Nothing 
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$FF59 OLDRST 



JFF65 



$EF© 






Old Monitor entry point. 

OLDRST sets up Lhe video display and keyboard as output and input devices. 
It sets hex mode, does not beep, and enters the Monitor at MONZ2. It does 
not return to caller. All Monitor 65C816 register storage locations are reset 
to standard values. 



Input 



A - ? 
X = ? 

Y = ? 



Output Does not return to caller 



MON 



Standard Monitor entry point, with beep, 



IN clears decimal mode, beeps bell, and enters the Monitor at MONZ. 
All Monitor 65816 register storage locations are reset to standard values. 



A = ? 
X- ? 
Y = ? 

Does not return to caller 



Input 

Output 

MONZ Standard Monitor entry point (Call -151), 

All Monitor 65816 register storage locations are reset to standard values. 
MONZ displays the * prompt and sends control to the Monitor input 
parser. 

Input A = ? 

X -? 

Y = ? 

Output Does not return to caller 

MONZ2 Standard Monitor entry point (alternate). 

MONZ2 does not change Monitor 65816 register storage locations. MONZ2 
displays the * prompt and sends control to the Monitor input parser. 

Input A = ? 
X-? 

Y = ? 

Output Does not return to caller 
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5FT70 MONZ4 



SFF8A 



No prompt Monitor entry point. 

MGNZ4 does not change Monitor 65816 register storage locations. No 
prompt is displayed. Control is sent to the Monitor input parser, 

Input A = ? 
X = ? 

V = ? 

Output Does not return to caller 

DIG Shift hex digit into A2I/A2H (addresses 53E/$3D. 

DIG shifts an ASCII representation of a hex digit in the accumulator into 
A2L/A2H (addresses S3E/S3F) and the exits into NXTCHR. 

Input 



Output 



SFFA7 GETNUM 



A = ASCII character EORed with 
X- ? 

Y - Entry point in input buffer $2xx at which to continue 
decoding characters 

Unchanged = DBR/K/D/e 

Scrambled - A/B/P/X 

Special - Y = Points to next character in input buffer at $2xx 

Transfer hex input into A21/A2H (addresses $3E/$31F). 



GETNUM scans the input buffer ($2xx) starting al position Y. It shifts hex 
digits into A2L/A2H (addresses S3B/53F) until it encounters a nonhex digit. 
It then exits into NXTCHR. 

Input A = ? 

X = ? 

Y = Entry point in input buffer $2xx at which to sLart decoding 
characters 

Output Unchanged = DBR/K/D/e 
Scrambled - A/B/P/X 
Special = Y = Points to next character in input buffer at $2xx 
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SFFAD NXTCIIR 



Translate nexi character. 



NXTCIIR is the loop used by GETNUM to parse each character in the input 
buffer and convert it 10 a value in A2L/A2H (address S3E/53F). ft also 
upshifts any lowercase ASCII values thai appear in the input buffer (addresses 
S2xx). 



Input 



Output 



SFFBE TOSUB 



A = ? 
X- ? 

Y = Entry point in input buffer S2xx al which to start decoding 
characters 

Unchanged ■ DBR/K/D/e 

Scrambled - A/B/P/X 

Special = Y = Points to next character in input buffer at $2xx 

Transfer control to a Monitor function. 



TOSUB pushes an execution address onto the stack and then performs an 
RTS to the routine, ft is of very limited use to any program. 

Input A = ? 

X = ? 

Y - Offset into subroutine table 

Output Unchanged = DBR/K/D/e 
Scrambled = A/B/P/X/Y 

SFFC7 ZMODE Zero out Monitor's mode byte MONMODE (address $31). 

ZMODE zeroes out MONMODE (address S31). 

Input A - ? 

X= ? 
Y-7 

Output Unchanged - A/X/DBR/K/D/e 
Scrambled = P/B 

Special - Y - $00 
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Appendix D 



Vectors 



This appendix lists Lhe Apple IIGS vectors. A vector is usually eilher a 2-byte address in 
page S00 or (possibly) a 4~byle jump instruction in a different bank of memory. 
Vectors are used to ensure a common interface point between externally developed 
programs and system-resident routines. External software jumps directly or indirectly 
through these vectors instead of attempting to locate and jump directly to the routines 
them.se Ives. When a new version of the system is released, die vector contents change, 
thereby maintaining system integrity. 

lor ail of the vectors defined in this chapter, the following definitions apply: 

□ A represents the lower 8 bits of the accumulator. 
E B represents the upper 8 bits of the accumulator. 

□ X and Y represent 8-bit index registers, 

□ DBR represents the data bank register. 
n represents the program bank register, 

□ P represents the processor status register 
D S represents the processor stack register. 

□ D i fits the direct-page register, 
e represents lhe emulation-mode bit, 

□ c represents the carry flag. 

v represents the overflow flag, 

□ ? represents a value that is undefined. 
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Bank $00 page 3 vectors 

SG3F0-S03F1 BRKV 



S03F2-S03F3 



5(1 3F4 



S03F5-S03F6-J3F7 



User DRK vector. 



S03FE-SO3HF 



Address of subroutine that handles BRK interrupts. Normally 
points to 01.DBKK (address SFA59) in Monitor ROM, 

SOFTEV User soft-entry vector for RESET, 

Address of subroutine thai handles warm start (RESET 
pressed). Normally points to BASIC or operating system. 



FWREDIJP 



EOR of high bylc of SOFTEV address. 



PWREDUP = SOFTEV + 1 EORed with constant $A5. If 
PWREDUP docs not equal SOFTEV + 1 EORed with constant 
3A5. system performs cold start. If PWREDUP equals 
SOFTEV + 1 EORed with constant $A5, system performs warm 
start. 

AMPERV Applesoft & JMP vector. 

Address of subroutine that handles Applesoft & (ampersand) 
commands Normally points to IORTS (address $FA58) in 
Monitor. Address S03F5 contains a JMP ($4Q opcode. 



S03F8-$03F9-$3FA USRADR 



User Control-Y and Applesoft. 

USR function JMP vector. 



Address of subroutine that handles user Control-Y and 
Applesoft USR function commands. Normally points to MON 
(address SFF65) in Monitor; points to BASIC.SYSTEM warm- 
start address if ProDOS 8 is loaded. Address $03F8 contains a 
JMP (S-iC) opcode 



S03FB-SO3FC-S3FD NMI 



User NMI vector. 



Address of subroutine that operating systems or applies lions 
can change to gain access to NMI interrupts. Normally points 
to OLDRST (address SFF59) in Monitor ROM or to operating 
system if one is loaded. Address 503FB contains a JMP ($4C) 
opcode 

IRQLOC User IRQ vector. 

Address of subroutine that operating systems or applications 
can change to gain access to IRQ interrupts. Normally points 
to MON (address $FF65) in Monitor ROM or to operating 
system if one is loaded. 



Bank S00 page 3 vectots 
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Bank $00 page C3 routines 



IC3H 



AUXMOVE Move data blocks between main and 

auxiliary 4BK memory. 

AUXMOVE is used by the Apple He and Apple lie to move 
data blocks between main and auxiliary memory, For 
compatibility reasons, Apple JIGS also supports this entry 
point if the 80-column firmware is enabled via the Control 
Panel, 



Input 



Output 



A = ? 
X= ? 

Y = ? 
c= 1 
c = 
AIL - 

A1H a 

A2L = 
A2H = 
A4L - 
A4H « 



■ Move from main to auxiliary memory 
= Move from auxiliary to main memory 

(Address S3C); source starting address, 

low-order byte 

(Address S3D>, source starting address, 

high-order byte 

(Address $3E>, source ending address, 

low-order byte 

(Address $3F); source ending address, 

high-order byte 

(Address S42); destination starting 

address, low-order byte 

(Address $43); destination starting 

address, high-order byte 



Unchanged = A/X/Y/DBR/K/D/e 

Changed - B/P 

A1L/A1H = (Addresses $3C/$3D)=l6-bit source 

ending address +1 
A2L/A2I1 - (Addresses 53E/$3F>l6-bit source 

ending address 
A4L/A4H = (Addresses S42/$43)=l6-bit original 

destination address + number of 

bytes moved + I 
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Appendix D: Vectors 



SC3H 



XFER 



Transfer program control between main 
and auxiliary 48K memory. 



XFER Ls used by the Apple lie and Apple lie to transfer control 
between main and auxiliary memory. For compatibility 
reasons, the Apple HGS also supports this entry point if the 
80-column firmware is enabled via the Control Panel. XFER 
assumes thai the programmer has saved the current stack 
pointer at $0100 in auxiliary memory and the alternate stack 
pointer at SO 101 in auxiliary memory before calling XFER and 
restores ihem after regaining control. Failure to restore these 
pointers causes program errors and incorrect interrupt 
handling. 

Input A ■ ? 

X = ? 
Y-? 

c = 1 = Transfer control from main to auxiliary 

memory 
c - ■ Transfer control from auxiliary to main 

memory 
v ■ i o Use page rera and stack in auxiliary 

memory 
v - = Use page zero and slack in main memory 
S03ED = Program starting address, low-order 

byte 
S03EE - Program starting address, high-order 
byte 

Output Unchanged - A/X/Y/DBR/K/D/e 
Changed = B/P 






Bonk $00 page C3 routines 
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Bank $00 page Fx vectors 

$FFE4-$FFE5 NCOP 



$FFE6-$FFE7 



SFFE8-SFFF.9 



SFFEA-$FFEB 



5FFEE-SFFEF 



Native-mode COP vecLar. 



This is not a callable routine. It is a 1 6-bit value that changes 
with each ROM release. Its value is not guaranteed No 
program should use this value, This vector is pulled from 
the ROM and used whenever a native-mode COP is executed. 



NBREAK 



Native-mode BRK vector. 



This is not a callable routine. It is a l6-bit value thai changes 
with each ROM release. Its value is not guaranteed. No 
program should use this value. This vector is pulled from the 
ROM and used whenever a native-mode BRK is executed 



NABORT 



Native-mode ABORT vector, 



This is not a callable routine. It is a 16-bit value that changes 
with each ROM release. Its value is not guaranteed, No 
program should use this value. This vector is pulled from the 
ROM and used whenever a native-mode ABORT is executed, 



NNM1 



Native-mode NM1 vector. 



This is not a callable routine. It is a 16-bit value that changes 
with each ROM release. Its value is not guaranteed. No 
program should use this value. This vector is pulled from the 
ROM and used whenever a native-mode NMI is executed. 



NIRQ 



Native-mode IRQ vector. 



This is not a callable routine. It is a 16-bit value diat changes 
with each ROM release. Its value is not guaranteed. No 
program should use this value. This vector is pulled from the 
ROM and used whenever a native-mode IRQ is executed. 
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SFFF4-SFFF5 



$FFF8-$FFF9 



SFFFA-SFFFB 



$FFFC-$FFFD 



ECOP 



Emulation-mode COP vector. 



This is not a callable routine. It is a 16-bit value thai changes 
wiih each ROM release. Its value is not, guaranteed. No 
program should use this value. This vector is pulled from the 
ROM and used whenever an emulation-mode COP is 
executed. 



EABORT 



Emulation-mode ABORT vector. 



This is not a callable routine. It is a 16-bit value that changes 
with each ROM release. Its value is not guaranteed. No 
program should use this value. This vector is pulled from the 
ROM and used whenever an emulation-mode ABORT is 
executed. 



ENMI 



Emulation-mode NMI vector. 



This is not a callable routine. It is a 16-bit value that changes 
with each ROM release. Its value is not guaranteed. No 
program should use this value. TJftls vector is pulled from Lhe 
ROM and used whenever an emulation -mode NMI is 
executed. 



ERF SET 



RESET vector. 



This is not a callable routine. It is a 16-bii value that changes 
witli each ROM release. Its value is not guaranteed. No 
program should use this value. This vector is pulled from the 
ROM and used whenever a RESET is executed. 



SFFFF-SFFFF 



EBRKJRQ Emulauon-made BHK/1RQ vector. 

This is not a callable routine. It is a l6-bil value that changes 
with each ROM release. Its value is not guaranteed. No 
program should use this value. This vector is pulled from the 
ROM and used whenever an emulation-mode BRK or IRQ is 
executed. 



Bank $00 page Fx vectors 
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Bank $E1 vectors 

The vectors DISPATCH 1 through SYSMGRV are guaranteed to be in the given 
ons in this and all future Apple lies— compatible machines. 



5E1/OOO0-00O3 



St 1/0004-0007 



SE1/0O08-0O0B 



SE1/000C-000F 



DISPATCH1 



Jump to tool locator entry type 1. 



Unconditional jump 10 lool locator entry type I . JSL from 
user's code directly to the tool locator with this entry poinL 
The form of the call in memory is as Follows: 

JMP abslong (S5C/low byte/high byte/bank byte) 



DLSPATCH2 



Jump lo tool locator entry type 2. 



Unconditional jump to tool locator entry type 2. JSL to a JSL 
from user's code to the tool locator with this entry point. The 
form of the call in memory is as follows; 

JMP abslong C$5C/low byte/high byte/bank byte) 

UD IS PATCH 1 Jump to tool locator entry type 1. 

Unconditional jump to user-installed lool locator entry type 

1. JSL from user's code directly to the user-installed tool 
locator with this entry point. The form of the call in memory 
is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 

UDISPATCH2 Jump to tool locator entry type 2. 

Unconditional jump to user-installed tool locator entry type 

2. JSL to a JSL from user's code to the user-installed tool 
locator with this entry point. The form of the call in memory 
is as followsr 

JMP abslong ($5C/low byte/high byte/bank byte) 



$ El /00 10-00 13 



INTMGRV 



Jump to system interrupt manager. 



Unconditional jump to the main system interrupt manager. 
If the application patches out this vector, the application 
must be able to handle all interrupts in the same fashion 
as the built-in ROM interrupt manager. Otherwise, the system 
will not, in most circumstances, run. The form of the call 
in memory is as follows: 

JMP abslong (S5C/low byte/high byte/bank byte) 



App§nd|x D: Y§St9f§ 



SEl/0014-0017 



COPMf.KV 



$E 1/00 18-00 IB 



JEI/OOK-OGIF 



Jump lo COP manager- 



Unconditional jump to COP (coprocessor) manager. 
Currently points to code that causes the Monitor to print a 
COP instruction disassembly, similar to the BRK 
disassembly. The form of the call in memory is as follows: 

JMP abslong (S5C/Iow byte/high byte/bank byte) 



ABOKTMGKV 



jump to abort manager. 



Unconditional jump to abort manager. Currently points lo 
code thai causes the Monitor 10 prim the disassembly of the 
instruction being executed, similar to the BRK disassembly. 
The form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



SYSDMGRV 



Jump to system failure manager. 



Unconditional jump to the system failure manager. This 
call assumes the Following: 

□ Entry is in 16-bil native mode. 

a c (carry) = if user-defined message is poinled to on stack; 
c - \ if the default value is used 

□ The stack is set up as follows: 

9,5 = Error high byte 
8,S = Error low byte 
7,S = Null byte of message address 
6,S ■ Bank byte of message address 
5,S = High byte of message address 
4,S B Low byte of message address 
3,5 = Unused return address 
2,S = Unused return address 
1,S ■ Unused return address 

The form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



Bonk SE1 vectors 
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IRQ.APTALK and IRQ.SERIAL vectors 

Veciors 1RQ.APTALK and IRQ.SERIAL are normally set up to point lo the internal 
interrupt handier or to code that sets carry and then performs an RTL back to the 
Interrupt manager. All the routines are called in 8-bit native mode and at high speed, 
"the data bank register, the direct register, MSLOT ($7F8), and the stack pointer arc 
not preset or set as for other interrupt vectors. The called routine must return carry 
clear if lite routine handled the interrupt and carry set if it did not handle the interrupt. 
Carry clear tells the interrupt manager not to call the application or operating system 
Carry set tells the interrupt manager that the application or the operating system must 
be notified of the current interrupt. The called routines must preserve the DBR, speed, 
S-bit native mode, D register, stack pointer (or just use current slack), and MSLOT for 
proper operation. A/X/Y need not be preserved Interrupts are disabled on entry to 
all interrupt handlers, The user's interrupt handler must not reenable interrupts from 
within the handler. AppleTaJk and the Desk Manager are allowable exceptions. These 
vectors should be accessed only via the Miscellaneous Tool Set Their location in 
memory is not guaranteed. 



SE1/0020-O023 



SE1/0024-0027 



IRQ.APTALK Jump to AppleTalk interrupt handler. 

Unconditional jump to the AppleTalk LAP (link access 
protocol) interrupt handler. Handles SCC interrupts 
intended for AppleTalk. The form of the call in memory is 
as follows: 

JMP abslong C$5C/low byte/high byte/bank byte) 



IRQ.SERIAL 



Jump to serial-port interrupt handler. 



Unconditional jump to serial-port interrupt handler. 
Hiu'j.llt-s interrupts intended fbi serial ports Tbc fbran of the 
call in memory is as fotlowg: 

JMP abslong ($5C./low byte/high byte/bank byte) 



I 
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i^i^i^i^iM 



IRQ.SCAN through IRQ.OTHER vectors 

Vectors IRQ.SCAN through IRQ.OTHER are normally set up to point to the internal 
interrupt handler or to code that sets carry and then performs an RTL back to the 
interrupt manager. All the routines are called in 8-bit native mode and with the high 
speed at data bank register set to $00 and the direct register set to S0OO0. The called 
routine musL return carry dear if it handled the interrupt and carry set if ii did not 
handle the interrupt. Carry clear tells the interrupt manager not to call the application 
or operating system. Carry set tells the interrupt manager that the application or the 
operating system must be notified of the current interrupL The called routines must 
preserve the DBR, speed, 8-bit native mode, and D register for proper operation. 
A/X/Y need not be preserved. Interrupts are disabled on entry to all interrupt 
handlers. The handler must not reenable interrupts from within the interrupt handler. 
AppleTalk and the Desk Manager arc allowable exceptions, These vectors should be 
accessed only via the Miscellaneous Tool Set. Their location in memory is not 
guaranteed. 

$E1/0028~Q02B IRQ.SCAN Jump to scan-line interrupt handler. 

Unconditional jump to the scan-line interrupt handler. 
Used by the Cursor Update routine, The form of the call 
in memory is as follows: 






SE1/002C-OQ2F 



SE1/0O3O-0O33 



SE1/0O34-O037 



JMP abslong (55C/low byte/high byte/bank byte) 



IRQ.SOUND 



Jump to sound interrupt handler. 



Unconditional jump to the sound interrupt handler. 
Handles all interrupts from the Ensoniq sound chip. The 
form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



IRQ.VBL 



Jump to VBL handler. 



Unconditional jump to the vertical blanking CVBL) interrupt 
handler. The form of the call in memory is as follows!: 

JMP abslong ($5C/low byte/high byte/bank byte) 



IRQ. MOUSE 



Jump to mouse interrrupt handler. 



Unconditional jump to the mouse interrupt handler. The 
form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



IRQ.SCAN through IRQ. OTHER vectors 
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SE1/0O38-003B 



SE1/003C-O03F 



5E1/0O4O-QO43 



AE1/0O44-OO47 



SE1/0048-004B 



IRQ.QTR 



Jump to quarter-second interrupt 
handler. 



Unconditional jump to the quarter-second interrupt handler 
Used by AppleTalk. The form of the call in memory is as 
follows: 

JMP abslong ($5C/low byte/high byte/bank byte} 



IRQ.KBD 



Jump to keyboard interrupt handler. 



Unconditional jump to the keyboard interrupt handler, 
Currently the keyboard has no hardware interrupt. Keyboard 
interrupts are still available by making a call to die 
Miscellaneous Tool Set, telling it to install a heartbeat task 
that interrupts every time VBL polls the keyboard. If a key is 
pressed, the heartbeat task will JSL through this vector. This 
forms a quasi-key board interrupt. The form of the call in 
memory is as follows: 

JMP abslong ($5C/low byte/high byle/bank byte) 

IRQ.RESPONSE Jump to ADB response interrupt 
handler. 

Unconditional jump to the ADB (Apple DeskTop Bus} 
response interrupt handler. The form of the call in memory is 
as follows: 

JMP abslong ($5C/law byte/high byte/bank byte) 



IRQ.SRQ 



Jump to SRQ interrupt handler. 



Unconditional jump to the ADB (Apple DeskTop Bus) SRQ 
(service request) interrupt handler. The form of the call in 
memory is as follows: 

JMP abslong (S5C/low byte/high byte/bank byte) 



IRQ.DSKACC 



Jump to Desk Manager interrupt 
handler. 



Unconditional jump to the Desk Manager interrupt 
handler. Invoked by the user pressing ControI-tf-Esc. The 
form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



Appendix D: Vectors 



JE1/0O4C-0O4F 



$E 1/00 50-005 3 



SE1/0O54-0O57 



$E 1/00 58-005 B 



SE1/OO5C-0O5F 



SE I/OO6O-OO6 3 



IRQ, FLUSH Jump to keyboard FLUSH interrupt 

handler. 

Unconditional jump to the keyboard FLUSH interrupt 
handler. Invoked by the user pressing Contml-G-Backspace. 
The form of the call in memory b as Follows; 

JMP abslong (S5C/low byte/high byte/bank byte) 

IRQ.MICRO Jump 10 keyboard micro abort interrupt 

handler. 

Unconditional jump to the keyboard micro abort recovery 
routine. This interrupt occurs only when the keyboard micro 
has a catastrophic failure. If such a failure docs occur, the 
firmware will try to resynchronize up to the keyboard micro 
and initialize. The form of the call in memory is as follows; 

JMP abslong ($5C/low byte/high byte/bank byte) 



IRQ.1SEC 



Jump to 1-second interrupt handler, 



Unconditional jump to the 1-second interrupt handler, The 
form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 

IRQ. EXT Jump to VGC external interrupt handler. 

Unconditional jump to the VGC (video graphics chip) 
external interrupt handler. Currently, the pin that generates 
this interrupt is forced high so that no interrupt can be 
generated. This interrupt handler is for future system 
expansion and currently cannot be used The form of the 
call in memory is as folio ws: 

JMP abslong (S5C/low byte/high byte/bank byle) 

IRQ.OTHER Jump to other interrupt handler. 

Unconditional jump to an installed interrupt handler that 
handles interrupts other than the ones handled by the 
internal firmware. This is a general-purpose vector. The 
form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



CUPDATE 



Cursor Update vector, 



Unconditional jump to the Cursor Update routine in 
QuickDraw II. The form of the call in memory is as follows; 

JMP abslong (S5C/low byte/high byte/bank byte) 

IRQ,SCAN through IRQ.OTHER vectors 
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SE1/0064-0067 



M' l ■ 006&-0O6B 



SE1/0O6C-006F 



SE1/0070-0073 



INCBUSYFLG increment busy flag \v> in: 

Unconditional jump to the increment busy flag routine. The 
form of the call in memory is as follows: 

JMP abslong ($5C/Iow byte/high byte/bank byte) 

DECBUSYFLG Decrement busy flag vector. 

Unconditional jump to the decrement busy (lag routine. The 
form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 

BELLVECTOR Monitor bell vector intercept routine. 

Unconditional jump to a user-installed BELL routine. The 
Monitor calls this routine whenever a BELL character ($87) 
is output through the output hooks (CSWL/CSWH $36/$37) 
and whenever BELLI, BELLI. 2, and BELL2 are called. The 
routine is called in 8-bit native mode and must return to the 
Monitor in 8-bit native mode. The data bank register and 
direct register must be preserved. Carry must be relumed 
clear, or the Monitor will generate its own bell sound For 
compatibility with existing programs, the X register must be 
preserved during this call, and Y must be ■ $00 on exit from 
this call. The form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 

BREAKVECTOR Break vector. 

Unconditional jump to a user-installed break vector. The 

user's routine is called in 8-bit native mode at high speed, 

with die data bank register set to $00 and the direct register 

set to SOOOO. The user's routine must preserve the data bank 

register, direct register, and speed and return in 8-bit native 

mode Willi an RTL. The user's routine must also clear carry, or 

the normal break routine pointed to by the vector at 

S00/O3FO.Q3F1 will be called. If carry comes back clear, the 

break interrupt is processed and the application program is 
resumed 2 bytes past the BKK opcode, '(his vector is set up for 

um: by debuggers such as the Apple His debuggei rhe farm 

of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 
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SE1/0074-0077 



TRACEVECTOR Trace vector. 

Unconditional jump 10 a trace vector. The user's routine Is 
called in 8*bit native mode at high speed, with the data bank 
register set to £00 and the direct register set to $0000. The 
user's routine musj preserve the data bank register, direct 
register, and speed and return in 8-bit native mode with an 
RTL. If the user's routine clears carry, the Monitor Brows 
resumes where it left o(T. If the user sets carry, the Monitor 
firmware currently will print Trace on the screen and continue 
where it left off. This vector is sei up for use by future system 
firmware and by current debuggers. The form of the call Ln 
memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank ; 



$E1/'0078-007B 



STEPVECTOR 



Step vector. 



Unconditional jump to a step vector. The user's routine is 
called in 8-bit native mode at high speed, with the data bank 
register set to $00 and the direct register set to S0000. The 
user's routine must preserve the data bank register, direct 
register, and speed and return in 8-bit native mode with an 
RTL If the user clears carry, the Monitor firmware resumes 
where it left off. If the user's routine sets carry, the Monitor 
firmware currenUy will print Step on the screen and continue 
where it left off. This vector is set up for use by fi p 

firmware and by current debuggers. The form of the call in 
memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



SE1/007C-007F 



Reserved for future expansion. 

This vector is reserved for future system expansion and is not 
available to the user. The form of the call in memory is as 
follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



sr?Q,sCAN through irq.qther vectors 
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TOWR1TEBR through MSGPOINTER vectors 

Vectors TOWRITEBR Lhrough MSGPOINTER are guaranteed to stay in the same 
memory locations in all Apple EGS-compatible systems. These vectors arc for 
convenience and are not to be altered by any application. 

SE1/0080-0083 



TOWRITEBR 



Write BATTER YRAM routine. 



This vector points 10 a routine that copies the 
BATTERYRAM buffer in bank $Et eo the dock chip 
BATTERYRAM with proper checksums. This routine is 
called by the Miscellaneous Tool Set and by the Control 
Panel. The form of the call in memory is as follows; 

JMP abslong (S5C/low byte/high byte/bank byte) 



$£■1/0084-0087 



TOREADBK 



Read BATTERYRAM routine, 



5E1/0088-008B 



This vector points to a routine that copies the clock chip 
BATTERYRAM lo the BATTERYRAM buffer in bank SE1, 
compares the checksums, and if the checksums match, 
returns to the caller. IF the checksums do not match or if one 
of the values in the BATTERYRAM is out of limits, the system 
default parameters are written into the BATTERYRAM buffer 
in bank $E1 and then into the clock chip BATTERYRAM 
with proper checksums. This routine is called by the 
Miscellaneous Tool Set and by the Control Panel. The form 
of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 

TOWRITETIME Write time routine. 

This vector points to a routine that writes to the seconds 
registers in the clock chip. It transfers the values in the 
CLKWDATA buffer in bank SKI to the clock chip. This routine 
is called by the Miscellaneous Tool Set only. It returns carry 
clear if the write operation was successful and carry set if it 
was unsuccessful, The form of the call in memory is as 

follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



Appendix D: vectors 




SE1/008C-008F 



SE1/O090-O093 



TORFADTTMF 



Read time routine. 



This vector points to a routine that reads from the seconds 
registers in the clock chip, It transfers the values to the 
CI.KRDATA buffer in bank SE1 to the clock chip. This routine 
is called by the Miscellaneous Tool Set only. It returns carry 
dear if the read operation was successful and carry set if it was 
unsuccessful, The form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 

TOCTR1.PANEL Show Control Panel. 

This vector points to the Control Panel program. It assumes 
il was called from the Desk Manager. It uses most of zero 
page. It RTLs back to the Desk Manager when Quit is chosen. 
The form of the call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



SE1/0094-O097 



TOB RAM SETUP 



5E1/O098-O09B 



Sct up system to BATTERYRAM 
parameters routine. 



This vector points to a routine lhat sets up the system 
parameters to match the values in the BATTERYRAM buffer. 
In addition, if it is called with carry clear, it sets up the slot 
configuration (internal versus external). If it is called with 
carry set, it does not set up the slot configuration (internal 
versus external). BATTERYRAM buffer $E1 values can be set 
via the Miscellaneous Tool Set only, The form of the call in 
memory is as folio ws; 

JMP abslong (55C/low byte/high byte/bank byte) 



TOPKINTMSG8 



Print ASCII string designated by ihe 
8-bit accumulator. 



This vector points to a routine lhat displays ASCII strings 
pointed to by multiplying the 8-bit accumulator times 2 
(shifting it left 1 bit) and then indexing into the address 
pointer table pointed to by MSGPOINTER (address 
$F.VOOC0; 3-byte pointer). It then uses thai address to get 
the string to display. This routine is used by the built-in 
Control Panel, by any text-based RAM Control Panel, 
and by the Monitor (to display messages). The form of the 
call in memory is as follows: 

JMP abslong ($5C/low byte/high byte/bank byte) 



TOWRITEBR through MSGPOINTER vectors 
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w^mm 



JE1/009C-O09F 



TOPRINTMSG16 



SE1/O0A0-OOA3 



SE1/O0A4-O0A7 



5E1/O0A&-0OBF 



Print. ASCII string designated by the 
1 6-bit accumulator. 



This vector points to a routine that displays ASCII strings 
pointed to by the 1 6-bit A register. The accumulator is used 
to index into the address pointer table pointed to by 
MSGPOINTER (address $E1/00C0; 3*byte pointer). It then 
uses that address to get the string to display. This routine is 
used by the built-in Control Panel, by any text-based RAM 
Control Panel, and by the Monitor (to display messages). 
The form of the call in memory is as follows: 

JMP abslong C$5C/low byte/high byte/bank byte) 

CTRLYVECTOR User Control -V vector. 

Unconditional jump to a user-defined Control- Y vector. The 
user's routine is called in 8-bit native mode, with the data 
bank register set to $00 and the direct register set to SO000. 
The user's routine must preserve the data bank register, direct 
register, and speed and return in emulation mode with an RTS 
from bank $00. If no debugger vector ts installed, the Monitor 
firmware will go to the user's routine via the normal 
Control- Y vector in bank $00 (USRADR O0/O3F8.O3F9.O3FA). 
This vector is set up to be used by debuggers. The form of the 
call in memory is as follows; 

JMP abslong ($5C/low byte/high byte/bank byte) 

TOTEXTPG2DA Point to Alternate Display Mode desk 
accessory. 

This vector points to the Alternate Display Mode program. It 
assumes it was called from the Desk Manager. It RTLs back to 
the Desk Manager when a key is pressed The form or the call 
in ffigmofy ig as fellows: 

JMP abslong CS5C/low byte/high byte/bank byte) 



PR016.MLI 



ProDOS 16 MLI vectors. 



This vector points to the ProDOS 16 routines. Consult 
ProDOS 16 documents for information about these calls. 
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SE1/QOC0-00C2 



MSGPOINTER 



Pointer to all strings used in Control 
Panel, Alternate Display Mode, and 
Monitor system messages. 



This 3-byte vector points to the address pointer table that 
points to ASCII strings used by the Control Panel, Alternate 
Display Mode, and Monitor system messages. It is not 
useful for users. The form of the call in memory is as 
follows; 

low byte/high byte/bank byte 



TOWRITEBR through MSGPOINTER vectors 
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Appendix E 



Soft Switches 



This appendix contains a list of the Apple IIGS soft switches — Lhe locations at which 
various program-definable system control options may be accessed and changed. 
Nole that this listing of soft switches is provided for reference only. You should < hangc 
the contents of a soft switch only by using the appropriate tool from the toolbox. Refer 
to 'he Apple flcs Toolbox Reference for more information. 



Important 

If you choose to change the contents of any of the soft switches (not 
recommended other than by using the toolbox routines) for any bit that is listed 
herein as undefined, you should mask that bit. In other words, read the current 
contents of the data byte, modify only the bits that are defined, and write the 
contents back to the switch location, 



Tables E-l and E-2 are symbol tables sorted by symbol and address. 



CQQO: C000 20 IOADR EQU * 

C0OO: C000 21 KBD EQU * 

C000:00 22 CLR8QCOL DFB C 

CO01:0O 23 SET80COL DFB 

C002:0O 24 RDMAINRAM DFB 

C003:00 25 RDCARDRAM DFB 

C004:00 26 WRMAINRAM DFB 

C005:00 27 WRCARDRAM DFB 

COO 6: 00 28 SETSLOTCXROM DFB 

rrtfl7iQQ 3 CBTriwcjtnoM Dffn 

C0O8:O0 30 SETSTDZP DFB 

C009:00 31 SETA1TZF DFB 



;A11 I/O is at SCxxx 
;Bit 7 = 1 if keystroke 
;Bitg 6-0 = Key pressed 
^Disable 80-column store 
; Enable 80-column store 
;Read from main 48 K RAM 
;Read from alternate 48K RAM 
; Write to main 4&K RAM 
;Write to alternate 48K RAM 
,*Use ROM on cards 

, Uiac; -L«»L«J.Uc4l ROW 

;Use main zero page/gtack 
;Use alternate aero page/stack 
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COOA.-00 
C00B:O0 
C00C:OO 
CQQDiOQ 
C0OE:0O 
COOF:0O 
COlO:00 
C011:0O 
C012:00 
C013:00 
C014:00 
CO15:0O 
C016:00 
C017:OO 
GO 18: 00 
C019t00 
C01A:00 
COlBrOO 
CQ1C:00 
C01D:00 
COlErOO 

COIF: 00 
C020:0O 



C021 
C021 
C021 

C021 
C021 
C021 
C021 

C021 
C021 
C021 
C021 



00 



C022 
C022 
C022 
C022 
C022 
C022 ; 

C022: 



32 SETTNTC3R0M 

33 SETSL0TC3R0M 

34 CLR80VID 

35 SET80VID 

36 CLRALTCHAR 

37 SETALTCHAR 

38 KBDSTRB 

39 RDLCBNK2 

40 RDLCRAM 

41 RDRAMRD 

42 RDRAMWRT 

43 RDCXROM 

44 RDALTZP 

45 RDC3R0M 

46 RD80COL 

47 RDVBLBAR 

48 RDTEJCT 

49 RDMIX 

50 RDPAGE2 

51 RDHIRES 

52 ALTCHARSET 

53 RD80VID 
54 



56 * 

57 * 

58 * 

59 * 

60 * 

61 * 

62 * 



"j 



I Enable 
I color/ 
I mono 
I 



DFB 


C 


DFB 





DFB 


Q 


DFB 





DFB 





DFB 


Q 


DFB 





DFB 





DFB 





DFB 





DFB 





CFB 





DFB 


D 


DFB 


D 


DFB 





DFB 


Q 


DFB 





DFB 





DFB 





DFB 





DFB 





DFB 


c 


DFB 






I 



; Enable internal slot 3 ROM 
; Enable external slot 3 ROM 
/Disable 80-column hardware 
; Enable 80 -column hardware 
/Normal LC, flashing UC 
/Normal inverse, LC; no flash 
.-Turn off keypressed flag 



;Bit 7 
/Bit 7 
;Bit 7 
;Bit 7 
;Bit 7 
/Bit 7 
/Bit 7 
-•Bit 7 
/Bit 7 
/Bit 
/Bit 
/Bit 
/Bit 
/Bit 



1 if LC bank 2 is enabled 

1 if LC RAM read enabled 

1 If reading alternate 48K 

1 if writing alternate 48K 

1 if using internal ROM 

1 if slot zp enabled 

l if slot c3 space enabled 

1 if 80-column store 

1 if not VBL 

1 if text (not graphics) 

1 if mixed mode on 

1 if TXTPAGE2 switched in 

1 if HIRES is on 

1 if alternate character 

set in use 

/Bit 7 - 1 if 80-column hardware on 

/Reserved for future system 

expansion 



MONOCOLOR status byte 



64 * 

65 * 

66 * 



MONOCOLOR bits defined as follows; 

Bit 7=0 enables color, 1 disables color 

Bits 6, 5, 4, 3, 2, 1, must be 

MONOCOLOR DFB /Monochrome/color selection register 



70 
71 
72 
73 
74 
75 



c 



I I I 

Text color bits 

_l I I 



I 



Background color bits 
I I I 



76 * 



tbcolor byte 
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CO 2 2 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 
C022 



00 



78 


j 


79 


* 


80 


it 


ex 


* 


82 


r 


83 


•. 


84 


* 


85 


* 


66 


* 


B7 


■ 


88 


* 


89 


* 


90 


* 


91 


* 


92 


* 


93 


* 


94 


* 


95 


* 


96 


* 


97 


* 


98 


* 


100 





TECGLOR bits Safined aa follows: 

Bits 7, 6, 5, 4 = Text color bits 

Bits 3, 2, 1, ** Background color bit3 

Color bits = 
$0 = Slack 
$1 ■ Deep red 

52 = Dark blue 

53 = Purple 

$4 ■ Dark green 

55 = Dark gray 

$6 = Medium blue 

$1 b* Light blue 

5B = Brown 

59 = Orange 

5A = Light gray 

SB - Pink 

$C = Green 

$D - Yellow 

$E ™ Aquamarine 

$F => White 

TBCOLOR DFB 



; Text/background color selection 
register 



C023; 
C023: 
C023: 
C023: 
C023: 
C023; 
C023 

C023: 

C023: 

C023; 

C023 

C023; 

C023 
C023 
C023 
C023 

C023;00 



102 * 7 

103 *| 

104 * ! VGC 

105 *]lnt 

106 * | active 

107 *J 

108 * " 

110 * 

111 * 

112 * 

113 * 

114 * 

115 * 

116 * 

117 * 

118 * 

120 



Q 



I I 
Isec [Scan |Ext 
Int lint |int 
active I active I 
I I 



I I I 
I lsec | Scan | Ext I 

1 int I int | int I 
I enable I enable t enable I 

I I I I 



VGC1NT status byte 



Bit 
Bit 

Bit 



VGCINT bits defined as follows: 

Bit 7 = 1 if interrupt generated by VGC 

6 = 1 if 1-second timer interrupt 

5 - 1 if scan-line interrupt 

4 = 1 if external interrupt (forced low in 
Apple lies) 
Bit 3 must be 

Bit 2 = 1-second timer interrupt enable 
Bit 1 ** scan-line interrupt enable 
Bit = ext int enable (can't cause an int in 

Apple He ij 
VGCINT DFB ;VGC interrupt register 
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fl 






C024 


: 122 * 


7 6 5 4 3 2 1 





C024 


123 * 


1 111,11 


1 1 


C024 


: 124 * 


1 Button I | 




C024 


: 125 * 


(status J Delta | Delta movement 




CO 2 4 


: 126 * 


[now Isign 




C024 


: 127 * 

: 128 * 


1 1 1 1 1 1 1 


1 1 


C024 


AAAA " MOUSEDATA byte *«*** 




C024 


: 130 * 


MOUSEDATA bits defined as follows: 




C024 


131 * 


Bit 7 = button 1 status if reading x data 




C024 


: 132 * 


button status if reading Y data 




C024 


: 133 * 


Bit 6 - sign of delta = '+' - 1 = '-' 




C024 


134 * 


Bits 5, 4, 3, 2, 1, = Delta movement 




C024 


:00 136 


MOUSEDATA DFB ; X or Y mouse data register 




C025 


: 138 * 


1 6 5 4 3 3 





C025 


: 139 * 


t I Update 1 | | 




C025 


: 140 * 


Open | Closed 1 mod 1 Keypad I Repeat (Caps Ctrl 


1 Shift 1 


C025 


l 141 * 


Apple | Apple |no key] key | active flock key 


1 key | 


C025 


142 * 


key |key | press lactivel 1 active active 


i active | 


C025 


143 * 

144 * 





| 


CQ25 


-**** KEYMODREG Statu9 byte •»*•** 




C025 


146 * 


KEYMODREG bits defined as follows: 




C025 


147 * 


Bit 7 - d key active 




C025 


148 * 


Bit 6 - (4 key active 




C025: 


149 * 


Bit 5 = Updated modifier latch without keypress 




C025, 


150 * 


Bit 4 - Keypad key active 




CO 25 


151 * 


Bit 3 = Repeat active 




C025: 


152 * 


Bit 2 ■ Caps lock active 




C025: 


153 * 


Bit 1 - Control key active 




C025: 


154 * 


Bit = Shift key active 




C025: 


00 156 


KEYMODREG DFB ;Key modifier register 




C02 6: 


158 * 


7 6 5 4 3 2 1 


o 


C026: 


159 *[ 


1 1 f 1 1 f 1 




C02fi : 


160 *| 


• 'l|| 




C026: 


161 *| 


Data to /from keyboard micro 




C026: 


162 *| 






C026: 


163 *| 

164 * 


1 1 J 1 1 1 1 




C026: 


*~ nnn DATAREG hvte aa« aa 
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C026: 
C026: 

C02 6: 
C02 6: 

C026 

C026 
C02 6 
C026 
C02 6 
C026 

C026: 
C026: 
C026:00 



166 * 

167 * 

168 * 

169 * 

170 * 

171 * 

172 * 

173 * 

174 * 

175 * 

176 * 

177 * 
179 



DATAREG bits defined as follows: 

Bits 7, 6 r 5, A, 3, 2, 1, = Data to/ from keyboard 

micro 

Data at interrupt time in this register defined as 

follows: 

Bit 1 = Response byte if set; otherwise, status byte 

Bit 6 • ABORT valid if set, and all other bits reset 

Bit 5 = Desktop Manager key sequence pressed 

Bit 4 = Flush buffer key sequence pressed 

Bit 3 ■ SRQ valid if set 

Bits 2, 1, 0; if all bits clear, then no FDB data 

valid; otherwise the bits indicate the number of valid 

bytes received minus 1 (2-8 bytes total) 



DATAREG 



DFB ;Data register in GLQ chip 



C027 
CO 2 7 
C02 7 
C027 
C027 
C027 
C027 



181 h _ 

182 *| 

183 *| 

184 *| 

185 *1 

186 * | 

187 * 



Mouse 

reg 

full 



1 



| Mouse | Data 
I int | reg 

I enable I full 



I 

I Data 

lint 

I enable 



Key I Key I Mouse |Cmd 
data lint |x/Yreg|reg 
full | enable | data |full 



KM STATUS byte 



C027 
C027 
C027 
C027 
C027 
C027 
C027 

C027: 

C027: 

C027: 

C027:00 

C028:00 



189 
190 

191 
192 

I 4 3 

194 
195 



196 * 

197 * 

198 * 
200 
201 



KMSTATUS bits defined as follows : 

Bit 7 = 1 if mouse register full 

Bit 6 ■ mouse interrupt disable /enable 

Bit 5 = 1 if data register full 

Bit 4 = data interrupt enable 

Bit 3 ■ 1 if key data full (never use, won't work) 

Bit 2 = key data interrupt enable (never use, won't 

work} 
Bit 1 = 0** mouse 'X' register data available 

1 = mouse 'Y' register data available 
Bit = Command register full 

KMSTATUS DFB ;Keyboard/mouse status register 
ROMBANK DFB /ROM bank select toggle (not used in 

Apple IlCfS) 
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PJ 


[ C029 


: 203 


* 


7 6 S 4 3 2 1 




CQ29 


: 204 


* 


II 1 1 1 1 1 




| C029 


: 205 


* 


Enable | Linear | B/W 1 I I | I Enable | 




1 C029 


: 206 


" 


super | video | Color | | | | (bank If 




C029 


: 207 


* 


hi-res | |DHirea| | | | Ibatch | 




C029 
C029 


: 208 
: 209 


* 

* 


II 1 1 1 1 1 


««"«* newvideo byte "" AA * 




CD29 


; 211 


* 


NEWVIDEO bits defined as follows: 




C02 9 


212 


* 


Bit 7=1= Disable Apple lie video {enables super 




C029 






hi-res) 




213 


« 


Bit 6=1 to linearize for super hi-res 




C029 


214 


* 


Bit 5-0 for color double hi-res; l for B/W nitres 




C02 9 


215 


* 


Bits 4, 3, 2, l must be 




C02 9 


216 


* 


Bit - Enable bank 1 latch to allow long instructions 
to access bank 1 directly; set by Monitor 




C02 9 


217 


+ 


only; a programmer must not change this bit. 




C029 


00 219 




NEWVIDEO DFB ; Video/enable read alternate mem 

with long instructions 




CQ2A 


00 220 




dfb ; Reserved for future system 
expansion 




C02B 
C02B 


222 

223 


Ik 
*l 


7 6 5 4 2 1 




1 1 1 1 1 1 1 




C02B 


224 


*| 


Character Generator | NTSC/|Lang 1 1 1 I 




C02B 


225 


k 


language select 1 PAL I select 10 | | | 




C02B 


226 


* 


1 Ibit 1 1 I | 




C02B 


227 

22fl 


* 
* 


1 1 1 1 1 1 1 1 




.saaa-a LANCEEL byts aaaaa 




C02B 


230 


* 


LANGSEL bits defined as follows: 




C02BJ 


231 


* 


Bits 7, 6, 5 = Character-generator language selector 




C02B; 


232 


* 


Primary language Secondary language 




C02B: 


233 


* 


50 = English (USA) Dvorak. 




C02B: 


234 


1 


$1 = English (UK) USA 




C02B: 


235 


-r 


$2 - French USA 




C02B: 


236 


* 


S3 = Danish USA 




C02B: 


237 


* 


34 = Spanish USA 




C02B: 


236 


-' 


$5 - Italian USA 




C02B: 


239 


ft 


$6 - German USA 




C02B: 


240 


* 


$7 = Swedish USA 




C02B: 


241 


t 


Bit 4 = if NTSC video mode, 1 if PAL video mode 




C02B; 


242 


A 


Bit 3 = LANGUAGE switch bit if primary lang set 
selected 




C02B: 


243 


I 


Bits 2, 1, must be 




C02B: 


00 245 




LANGSEL DFB ; Language/PAL/NTSC select register 




CC2C ; 


00 246 




CHARROM DFB ;Addr for tst mode read of character 

ROM 
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C02D 




248 


* 


7 


6 5 


4 3 


2 1 


Q 


C02D 




249 


* 


1 


1 1 


1 1 1 


1 1 




C02D 




250 


+ 


|Slot7 


I Slot 6 ISlotS | Slot 4 | |Slot2 |Slotl I 




C02D 




251 


* 


1 intext | intext | intext | intext | | intext 1 intext 1 


o 1 


C02D 




252 


* 


enable I enable | enable 1 enable 1 1 enable 1 enable 1 




C02D 




253 

2 '_■ 4 


* 

* 




1 


1 1 


1 1 




- - 






:l byte " AArt '* 






C02D 






C02D 




256 


* 


SLTROMSEL bits defined as follows: 






C02D 




257 


i 


Bit 


7=0 enables 


internal slot 7, 1 


enables slot 


ROM 


C02D 




258 


* 


Bit 


6=0 enables 


internal slot 6, 1 


enables slot 


ROM 


C02D 




259 


* 


Bit 


5=0 enables 


internal slot 5, 1 


enables slot 


ROM 


C02D 




260 


* 


Bit 


4=0 enables 


internal slot 4, 1 


enables slot 


ROM 


C02D 




261 


i 


Bit 


3 must be 








C02D 




262 


* 


Bit 


2=0 enables 


internal slot 2, 1 


enables slot 


ROM 


C02D 




263 


t 


Bit 


1=0 enables 


internal slot l f 1 


enables slot 


ROM 


C02D 




264 


* 


Bit 


must be 








C02D 


:00 


266 




SLTROMSEL DFB 


;Slot ROM select 






C02E 


:00 


267 




VERTCNT DFB 


;Addr for read of 


video cntr bits 














V5-VB 






C02P 


:00 


2ee 




HORIZCNT DFB 


;Addr for read of 


video cntr bits 














VA-H0 






C030 


:00 


269 




SPKR DFB 


; Clicks the speaker 




C031 




271 
272 




1 

1 


6 5 


4 3 


2 1 





C031 








C031 




273 


+ 


t 3 . 5- 


13.5" | 








C031 




274 


* 


head 


1 drive | 


t 1 | 


1 | 


| 


C031 




275 


* 


(Select 1 enable | 








C031 




276 
277 


* 

* 




1 








C031 


AAA * A DISKREG 








C031 




279 


■* 


DISKREG bits defined as follows: 






C031 




2B0 


* 


Bit 


7 - 1 to select head on 3.5" drive to use 




C031 




281 


* 


Bit 


6 = 1 to enable 3,5" drive 






C031 




2B2 


A 


Bits 5, 4, 3, 2, 1, must be 






C031 


00 


284 




DISKREG DFB 


;Used for 3*5" dig 


k drives 




C032. 




286 
287 


* 


7 


6 5 


4 3 


2 1 





C032: 


1 1 




| 


C032: 




2 a B 


* 




IClear IClear 1 I 




1 


C032: 




289 


* 





|1 sec | scan 


10 |0 | < 


10 | 


1 


C032: 




290 


A 




f int | In int I | 




1 


C032; 




2 91 
2 92 


T 
* 




1 1 






1 


C032: 


AAAAA SCANINT 
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C032 


294 * 


SCANINT bits defined as follows: 


C032 


295 * 


Bit 7 mu3t be 


C032 


296 * 


Bit 6 = Write here to reset 1-second interrupt 


C032 


297 * 


Bit 5 = Write here to clear scan-line interrupt 


CO 32 


298 * 


Bit 4 must be 


CO 32 


299 * 


Bit 3 must be 


C032 


300 * 


Bit 2 must be 


C032 


301 * 


Bit 1 must be 


C032 


302 * 


Bit must be 


C032 


00 304 


SCANINT DFB ;Scan-line interrupt register 


C033 


306 * 


7 £5 43 210 


C033 


307 *| 


1 1 1 1 1 1 1 1 


C033: 


30B *| 




CO 33. 


309 *| 


Clock data register | 


CO 33: 


310 *| 


| 


D033 


311 *| 

312 * 


1 1 1 1 1 1 1 1 


A " AAA CLOCKDATA byte AAA * A 


C033: 


314 * 


CLOCKDATA bits defined as follows; 


C033: 


315 * 


Bits 1, 6, 5, 4, 3, 2, 1, = Data passed to/from clock 

chip 


C033: 


00 317 


CLOCKDATA DFB ; Clock data register 


CO 34: 
C034: 


319 * 

320 *| 


6 5 4 3 2 l o 


1 1 1 1 I 1 


C034: 


321 *| Clock IRead/ Chip | | I 


CQ34: 


322 *|xfer | Write enable I I Border color 


C034; 


323 *| 


Ichip assert) 1 | 


C034: 
C034: 


324 *| 

325 * 


1 1 1 1 1 1 i 


****** CLOCKCTL byte **"** 


C034: 


327 * 


clqckctl bits defined as follows: 


C034: 


328 * 


Bit 7 = Set - 1 to start transfer to clock 


C034: 


329 * 


Read = when transfer to clock is complete 


C034: 


330 * 


Bit 6 - a Write to clock chip, 1 = Read from clock 

chip 


C034: 


331 * 


Bit 5 = Clk chip enable asserted after transfer 
- no/1 = yes 


C034: 


332 * 


Bit 4 must be 


C034: 


333 * 


Bits 3, 2, 1, = Select border color (see TBCOLOR for 

values) 


C034: 


00 335 


CLOCKCTL DFB /Clock control register 

Appendix E; Soft Switches 283 





C035 




337 


* 


7 




6 5 




4 J 2 10 


C035: 




338 


*l 








1 1 1 1 


C035. 




339 


*l 






Stop 


IStop IStop (Stop IStop IStop | 


C035: 




340 


*l 







I/O/LC 


I auxh-r | suprhr | hires2 | hires 1 I txpg | 


C035: 




341 


* ! 






shadow 


1 shadow 1 shadow I shadow 1 shadow I shadow I 


C035: 




342 

343 


* 








1 ! 1 1 1 1 


C035: 


***** SHADOW 


byte ***** 


C035: 


345 


•«■ 


SHADOW bits defined as follows: 


C035: 


346 


* 


Bit 


7 


must write 





CQ35: 


347 


* 


Bit 


B 


= 1 to inhibit I/O and language-card operation 


C035: 


348 


* 


Bit 


5 


must write 





C035: 


349 


* 


Bit 


4 


= 1 to inhibit shadowing aux hi-res page 


CO 3 h: 


350 


* 


Bit 


3 


= 1 to inhibit shadowing 32K video buffer 


CQ35: 


353 


* 


Bit 


I 


■ 1 to inhibit shadowing hi-res page 2 


C035: 


352 


' 


Bit 


1 


= 1 to inhibit shadowing hi-res page 1 


C035: 


353 


* 


Bit 


Cl 


= 1 to inhibit shadowing text pages 


C03S:QO 


355 




SHADOW DFB 


; Shadow register 


C036: 


357 
358 


* 
*l 


1 




5 5 


4 3 2 10 


C036 










1 111 


CQ36 




359 


*l 


Slow/ 






I Shadow | Slot 7| Slot 6 1 Slot 5 1 Slot 4 1 


C036 




360 


*l 


fast 




| 


I in alllmotor Imotor Imotor Imotor 


C036 




361 


*l 


speed 






|RAM | detect | detect 1 detect 1 detect I 


CO 3 6 




362 
363 


*l 
* 








1 III 


CO 3 6 










C036: 


365 


* 


CYAREC 


J bits defined as follows: 


CQ36: 


366 


T 


Bit 


7 


= = Slow 


system speed, 1 = Fast system speed 


C036: 


367 


* 


Bit 


6 


must write 





C03G; 


368 


.>. 


Bit 


5 


must write 





C03 6: 


369 


r 


Bit 


4 


" Shadow in all RAM banks (never use) 


C036: 


370 


* 


Bit 


3 


= Slot 7 disk motor on detect (set by Monitor 












only) 




C036: 


371 


T. 


Bit 


2 


- Slot 6 disk motor on detect (3et by Monitor 












only) 




C036: 


372 


* 


Bit 


1 


= Slot 5 disk motor on detect (set by Monitor 












only) 




C036: 


373 


* 


Bit 





= Slot 4 disk motor on detect (set by Monitor 












only) 




C036:00 


375 




CYAREC 


I DFB 




Speed and motor on detect 


C037:QG 


37 6 




DMAREC 


i DFB 




Used during DMA as bank address 


CQ38:0G 


377 




SCCBRE 


:g DFB 




SCC channel B cmd register 


C039:00 


37 B 




SCC ARE 


:g DFB 




SCC channel A cmd register 


C03A:00 


379 




SCCBD7 


LTA DFB 




■SCC channel B data register 


C03B 


00 


380 




SCCADi 


^TA DFB 




■SCC channel A data register 
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mil in 



■^^■■■H 




C03C 

C03C 

C03C 

C03C 

C03C 

C03C: 

C03C; 

C03C: 
C03C; 
C03C; 
C03C: 

C03C: 
C03C: 
C03C: 

C0 3C:00 

CQ3D: 

C03D- 
C03D: 
C03D: 
C03D: 
C03D: 
C03D: 

C03D: 
CO 3D: 

C03D:00 

C03E: 

C03E; 

C03E: 

C03E: 

C03E 

C03E 

C03E 

C03E; 
C03E: 

C03E:00 



382 *_ 

383 *" 

384 * 

385 * 

386 *| 

387 *| 
386 * 

390 * 

391 * 
3 92 * 

393 * 

394 * 

395 * 

396 * 

398 

400 *_ 

401 *| 

402 *| 

403 * | 

404 *| 

405 *| 

40 6 * 

408 * 

409 * 

■■ : i 



Busy 

flag- 



Auto I Access 
doc/ line 
RAM I adrpt r 



Volume DAC 



AAA A A 



SQUNDCTL byte 



SOUNDCTL bits defined as follows: 
Bit 7 = if not busy, 1 if busy 
Bit 6 - = Access doc, 1 = Access RAM 
Bit 5 - - Disable auto incrementing of address 
pointer 
1 = Enable auto incrementing of address pointer 
Bit 4 must be 
Bits 3, 2, 1, = Volume DAC-SQ/Sf = Low/full volume 

(write only) 
SQUHDCTL DFB ; Sound control register 

J 6 5 4 3 2 10 



Sound data read/written 



SOUNDDATA byte 



413 


tc 


414 


* 


415 


*\ 


416 


*\ 


417 


*l 


418 


*l 


419 


+ 


421 


ft 


422 


* 



SOUNDDATA bits defined as follows: 

Bits 7, 6, 5, 4, 3, 2, 1, - Data read from/ written to 

sound RAM 
SOUNDDATA DFB ; Sound data register 



e 



I I I I I 
Low byte of sound address pointer 

I !_ I I I 



SOUNDADRL byte 



A A -% A A 



424 



SOUNDADRL bit3 defined as follows: 

Bits 7, 6, 5, 4, 3 f 2, 1, 0- Address into sound RAM 

low byte 
SOUNDADRL DFB ; Sound address pointer, low byte 
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w^m 



C03F 
C03F 
C03F 
C03F 
C03F 
C03F 
C03F 

CQ3F; 

C03F: 



426 
427 

428 
429 
430 
431 
432 



* 

*i 

* 



« 5 A _3 2 

I I I I I 

High byte of sound address pointer 



I 



I 



^S A --. /■. -A. 



SOUNDADRH byte 



SOUNDADRH bits defined as follows: 

Bits 7, 6, 5, 4, 3, 2, l, = Address into sound RAM 

high byte 
SOUNDADRH DFB ; Sound address pointer, high byte 
DFB ; Reserved for future system 
expansion 

♦ Note; The Mega II mouse is not used under Apple Ilea as a mouse, but the 
soft switches and functions are used. Therefore, the programmer may not 
use the Mega II mouse soft switches. 



CQ3F:00 
CG40:0Q 



434 * 

435 * 

437 
438 



CO 41 
C041 
C041 
C041 
C041 
C041 
C041 



C041: 
CO 41: 
C041: 
C041: 
C041: 
C041: 
C041: 
CO 41: 

C041: 
C041:00 

CO42:O0 

C043:00 



440 



448 
449 
450 
451 
452 
453 
454 
455 
456 
458 

459 

460 




I I I I 
I Enable | Enable I Enable I Enable | Enable 
|l/4sec|VBL I switch | move |mou3e 
[ ints lints lints lints I 



INTEN 
Bit 7 
Bit 6 
Bit 5 
Bit 4 
Bit. 3 
Bit 2 
Bit 1 
Bit 
INTEN 



INTEN byte *"" 



bits defined as follows; 

must be 

must be 

must be 

= 1 to enable quarter-second interrupts 

= 1 to enable VBL interrupts 

1 to enable Mega II mouse switch interrupts 
■ 1 to enable Mega II mouse movement interrupts 
= 1 to enable Mega II mouse operation 

DFB ; Interrupt-enable register (firmware 

use only) 
DFB .-Reserved for future system 

expansion 
DFB ; Reserved for future system 
expansion 
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C044: 
C044: 
CQ44; 
CQ44: 
C044: 



462 



Z C 4 4 : 



463 * | 


1 1 1 1 1 1 1 1 


464 *| 




465 *| 


Mega II Mouse delta movement byte 1 


466 *| 




467 *| 


I I 1 1 J 1 1 1 


468 * 


***** MMDELTAX bvte * A 



CQ4 4: 
C0.4 4: 

C044:00 

C045: 
C045: 
C04S: 
C045: 
C045: 
C045: 
C045: 

C045: 

-n.;;., : 

C045:00 



C046 

C046 
C046 
C046 
C046 
C046 

m§ 

C046: 
C046: 

C046: 

C046: 



470 * MMDELTAX bits defined as follows: 

471 * Bits 7, 6, 5, 4, 3, 2, 1, = Delta movement in 2 f s 

complement notation 
473 MMDELTAX DFB ,Mega II mouse delta X register 




MMDELTAY byte **** 



MMDELTAY bits defined as follows: 

Bits 7, 6, 5, 4, 3, 2, i f - Delta movement in 2' a 

complement notation 
MMDELTAY DFB ;Mega II mouse delta Y register 



483* 

434 * 

486 

4 88 * __5 4 

489 *| III 

490 *|Self/ I MMouse! Status IStatus 

491 *1burnin |last |AN3 |l/4sec 
4 92 "Idiags | button I lint 
493 *| | | | 



Status | Status | Status I Status 
VBL I switch I move (system 
int | int I int | 



496 


». 


4 97 


• 


498 


- 


499 


* 



■•■■■- BIASTYPE feyte- HSfiftS 

DIAGTYPE bits defined as follows; 

Bit 7 = if self-diagnostics get used if BUTNO = 

1/BUTNl = 1 
Bit 1 = 1 if burn-in diagnostics get used if BUTNO 

1/BUTN1 - 1 
Bits 6-0 ■ Same as INTFLAG 
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2P7 



C04 6; 501 

C046: 502 

CQ46: 503 

C046; 504 

CQ46: 505 

C046: 506 

C046: 507 

C046: 509 

C046: 510 

C046: 511 

C046: 512 

C046: 513 

C046: 514 

C046: 515 

C046: 516 

C046: 517 
C046: C046 519 

CQ46:00 520 

C047:00 521 

C048:00 522 

C049:00 523 

C04A;00 524 

C04B:00 525 

C04C;00 526 

C04D:00 527 

C04E;00 528 

C04F:00 529 

C050:QO 530 

C051:00 531 

C052:00 532 

C053:00 533 

C054:00 534 

C055:00 535 

C056:00 536 

C057;00 537 

C058.-00 538 



* 7 

*l 

* | MMouse 

* | now 

* I button 
*l 



i 



- 



I I I I 1 I I 
I MMouse I Status I Status | Status I Status I Status | Status 
I last [AN3 ll/4sec|VBL f switch | move | system 
j button | |int lint | int lint I IRQ 
-I L L I I I I 



.** INTFLAG byte ***** 

INTFLAG bits defined as foili 

Bit 7 ■ 1 if mouse button currently down 

Bit 6 = 1 if mouse button was down on last read 

Bit 5 - Status of AN3 

Bit 4 = 1 if quarter-second interrupted 

Bit 3 = 1 if VBL interrupted 

Bit 2 = l if Mega II mouse switch interrupted 

Bit 1 = 1 if Mega II mouse movement interrupted 

Bit - 1 if system IRQ line is asserted 



DIAGTYPE 

INTFLAG 

CjuRVBLINT 

CLRXY1NT 



TXTCLR 

TXTSET 

MIXCLR 

MIXSET 

TXTPAGE1 

TXTPAGE2 

LORES 

HIRES 

SETAN0 



EQU * 
DFB 

DFE Q 

DFB 
DFB 

DFB 

DFB 

DFB 

DFB 

DFB 

DFB 

DF1 I 

DFB 
DFB 
DFB 
DFB 
DFB 
DFB 
DFB 
DFB 



;0/l Self/burn-i'n dd pumn**- i rq 

; Interrupt flag register 

; Clear the VBL/3.75Hz interrupt 

flags 

; Clear Mega II mouse interrupt flags 

; Reserved for future system * 

expansion 

/Reserved for future system 

expansion 

; Reserved for future system 

expansion 

; Reserved for future system 

expansion 

; Reserved for future system 

expansion 

;Re3erved for future system 

expansion 

-■Reserved for future system 

expansion 

; Switch in graphics (not text) 

; Switch in text (not graphing* 

."Clear mixed mode >-'.•' 

;Set mixed mode (4 lines text) 

/Switch in text page 1 

.•Switch in text page 2 

; Low- resolution graphics 

; High-resolution graphics 

; Clear annunciator 
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€059:00 


539 




CLRANO 


DFB 





; Set annunciator 




C05A:00 


540 




SETAN1 


DFB 





; Clear annunciatorl 




C05B:00 


541 




CLRAN1 


DFB 


3 


; Set annunciator 1 




C05C:00 


542 




SETAN2 


DFB 


j 


; Clear annunciator 2 




C05D:00 


543 




CLRAN 


DFB 





; Set annunciator 2 




COSE; 00 


544 




SETAN3 


DFB 





; Clear annunciator 3 




C05F:00 


545 




CLRAN3 


DFB 





; Set annunciator 3 




CQ60:00 


5 -\ 6 




BUTN3 


DFB 





;Read switch 3 




C061:00 


547 




BUTNO 


DFB 


II 


;Read switch (C3 key) 




C062:00 


548 




BUTN1 


DFB 





;Read switch 1 ftl key) 




C063:00 


549 




BUTN2 


DFB 





.-Read switch 2 




C064:00 


550 




PADDLQ 


DFB 





;Read paddle 




€065:00 


551 






DFB 





;Read paddle 1 




C066:0Q 


552 






DFB 





;Read paddle 2 




€067:00 


553 






DFB 





/Read paddle 3 




C068: 


555 


k 


7 


6 


5 


4 3 2 10 




C068: 


556 


* 


1 


1 




1 1 1 1 1 1 




C068: 


557 


*IALTZP |PAGE2 | RAMRD 


| RAMWRT | RDROM | LCBNK2 | ROMB f 1NTCX | 




CO 6S: 


558 


* 1 status I status | status I status | status I status f status | status I 




C068 : 


559 


*l 


1 


1 




111(11 




€068: 
C0S8: 


560 
561 


* 


1 


| 




1 1 1 1 1 1 






* STATEREG 






C068: 


563 


+ 


STATEREG bits defi 


ned as follows: 




C06B: 


564 


* 


Bit 1 m 


ALTZP status 




€068: 


565 


* 


Bit 6 = 


PAGE2 Status 




CO 58: 


566 


* 


Bit 5 = 


RAMRD 3tatU3 




1 €0 66: 


567 


# 


Bit 4 = 


RAMWRT 


sta 


tus 




CO 68: 


566 


* 


Bit 3 - 


RDROM status (read only RAM/ROM (0/1) J 




, €068: 


570 


* 


Important note 


; Pe 


rform two reads to SC0B3; then change 




€0 68: 


571 


* 


STATEREG to change 


LCRAM/ROM banks (0/1); keep the 




C068: 


572 


k 


language cacd write enabled. 




€058: 


573 


t 












COGS: 


575 


* 


Bit 2 = 


LCBNK2 


status = LC bank 0, 1 = LC bank 1 




COGS: 


576 


* 


Bit 1 - 


ROMBANK Status 




C06S: 


577 


* 


Bit = 


IHTCXROM status 




C06S:OO s 


579 




STATEREG "B 





; State register 




C069:00'* ' 


580 






DFB 





/Reserved for future system 
expansion 




C06A-00 


5fll 






DFB 


c 


; Reserved for future system 
expansion 
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C0 6B:00 

C0 6C:00 

C06D:00 

C06E:00 

C06F:00 

C07O:O0 

C071: 

C080-00 

C08l:0Q 

C0B2:OO 

CO 83: 00 

C084:00 

C085:00 

C066:QQ 
C087:00 

C088:00 

C089:00 

COBA:QO 
C0BB:OO 

COBCrOO 

C08D:00 

C08E:00 
C08F:00 

0000:610 
0000:612 



582 




DFB 


583 




DFB 


584 


TESTREG 


DFB 


585 


CLRTM 


DFB 


586 


ENTM 


DFB 


58 } 


PTRIG 


DFB 


588 




DS 15 r 


590 




DFB 



LCBANK2 



591 ROMIN 

592 

593 

595 

596 

597 
598 

600 

601 

602 
603 

605 

606 

607 
608 

DEND 
CLRROM EQU 



LCBANK1 



DFB 

DFB 
DFB 

DFB 

DFB 

DFB 
DFB 

DFB 

DFB 

DFB 
DFB 

DFB 

DFB 

DFB 
DFB 



/Reserved for future system 

expansion 

;Reserved for future system 

expansion 

;Teat mode bit register 

; Clear test mode 

/Enable test mode 

; Trigger the paddles 

;ROM interrupt code jump table 

,*Sel LC RAM bank2 rd, wrt protect LC 

RAM 

; Enable ROM read, 2 reads wrt enb LC 

RAM 

; Enable ROM read, wrt protect LC RAM 

;Sel LC RAM bank2, 2 rds wrt enb LC 

RAM 

;Sel LC RAM bank2 rd r wrt protect LC 

RAM 

; Enable ROM read, 2 reads wrt enb LC 

RAM 

,- Enable ROM read, wrt protect LC RAM 

;Sel LC RAM bank2, 2 rds wrt enb LC 

RAM 

;Sel LC RAM bankl rd, wrt protect LC 

RAM 

; Enable ROM read, 2 reads wrt enb LC 

RAM 

; Enable ROM read, wrt protect LC RAM 

;Sel LC RAM bankl, 2 rds wrt enb LC 

RAM 

;Sel LC RAM bankl rd, wrt protect LC 

RAM 

; Enable ROM read, 2 reads wrt enb LC 

RAM 

t Enable ROM read, wrt protect LC RAM 
;Sel LC RAM bankl, 2 rds wrt enb LC 

RAM 



SCFFF ; Switch out $C8 ROMs 
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Symbol table sorted by symbol 










CO 1 F 


ALTCHARSRT 


C06l 


BUTNO 


C062 BUTN1 


C063 


BL1TN2 


C060 


BUTN3 


C02C 


CHARROM 


C034 CLOCKCTL 


C033 


CLOCKDATA 


cooa 


CLR80COL 


cooc 


CLRBOVID 


COOE CLRALTCHAK 


C059 


CLRANO 


COSB 


CLRAN1 


C05D CLRAN2 


C05F CLEAN 3 


CFFF 


CLRROM 


CQ6E 


CLRTM 


co i ■ 


CLRVBL1NT 


C048 CLRXYINT 


C036 


CYAREG 


C026 


DATAREG 


C046 


DIAGTYPE 


C03I DISKREG 


C037 


DMA REG 


C06F 


5N1 M 


C057 


HIRES 


C02F HORIZCNT 


C041 


INTEN 


C046 


INTFLAG 


C000 


IOADR 


C010 KBDSTRB 


C0O0 


KBD 


C025 


KEYMODREG 


C027 


KMSTATUS 


C02B LANGSEL 


C08B 


LCBANK1 


C083 


LCBANK2 


C056 


LORES 


C052 MIXCi.K 


C053 


MIXSET 


C044 


MMDELTAX 


C045 


MMDELTAY 


C021 MONO COLOR 


C024 


MOUSEDATA 


G029 


NEWVIDEO 


C064 


PADDLO 


C070 PTRIG 


C0I8 


RD80COL 


COIF 


RD80V1D 


CO 16 


RDALTZP 


C017 RDC3ROM 


C003 


RDCARDRAM 


C015 


RDCXROM 


C01D 


RDHIRES 


C011 RDLCBNK2 


C012 


RDLCRAM 


COO 2 


RDMAINKAM 


C01B 


RDMIX 


C01C RDPAGE2 


C013 


RDRAMRD 


G0L4 


RDRAMWRT 


COtA 


KD'I KXT 


CO 19 RDVBLBAR 


C028 


ROMBANK 


O0B1 


ROM IN 


C032 


SCAN INT 


C03B SCC AD ATA 


C039 


SCCAREG 


C03A 


SCCBDATA 


C038 


SCCBREG 


C001 SET80COL 


COOD SET80VID 


coor 


SETALTCHAR 


C009 


SETALT2P 


C058 SETANO 


CO 5 A SETAN1 


C05C 


SETAN2 


COSE 


SETAN3 


COOA SETTNTC3ROM 


C007 


SETINTCXROM 


COOB 


SETS I.OTC3 ROM 


C006 


SETSLOTCXROM 


COOS SETSTDZP 


C035 


SHADOW 


C02D 


SLTROMSEL 


C03F 


SOUNDADRH 


C03E SOUNDADRL 


C03C 


SOUNPCTL 


C03D 


SOUNDDATA 


C030 


SPKR 


C068 STATEREG 


C022 


TBCOLOR C06 


C06D TESTREG 


CO 50 


TXTCLR 


C054 TXTPAGE1 


C055 


TXTPAGE2 


C051 


TXTSET 


C02E 


VERTCNT 


C023 VGCINT 


COOS 


WRCARDRAM 


C004 


WRMAJNRAM 
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rablo E-2 










Symbol table sorted by 


address 








C0O0 IOADR 


cooo 


KBD 


COOO CLR80COL 


C0O1 SET80COL 


C002 RDMAINRAM 


C003 


BDCARDRAM 


C004 WRMA1NRAM 


C005 WRCARDRAM 


C006 SETSLOTCXROM 


C007 


SETINTCXROM 


COOS SETSTDZP 


C009 SETALTZP 


COOA SETTNTC3ROM 


COOB 


SETSLOTC3ROM 


COOC CLR80V1D 


COOD SET80VID 


COOE CLRALTCHAR 


COOF 


SETALTCHAR 


C010 KBDSTRB 


C011 RDLCBNK2 


C012 RDLCRAM 


C013 


RDRAMRD 


C014 RDRAMWRT 


C015 RDCXROM 


C016 RDALT2P 


C017 


RDC3ROM 


C018 RD80COL 


C019 RDVBLBAR 


C01A RDTEXT 


CO IB 


RDMIX 


C01C RDPAGE2 


CO ID RDH1RES 


CO IE ALTCKARSET 


COIF 


RD80VID 


C021 MONOCOLOR 


C022 TBCOLOR 


C023 VGCINT 


C024 


MOUSEDATA 


C025 KEYiMODREG 


C026 DATAEEG 


C027 KMSTATUS 


C028 


ROM BANK 


C029 NEWVIDEO 


C02B LANGSEL 


C02C CHARROM 


C02D 


SLTROMSEL 


C02E VERTCNT 


C02F HORIZCNT 


C030 SPKR 


C031 


DISKREG 


C032 SCANINT 


C033 CLOCKDATA 


C034 CLOCKCTL 


C035 


SHADOW 


C036 CYAREG 


C037 DMAREG 


C038 SCCBREG 


C039 


SCCAREG 


C03A SCCBDATA 


C03B SCCADATA 


C03C SOUNDCTL 


C03D SOUNDDATA 


C03E SOUNDADRI 


C03F SOUND AD RH 


C041 INTEN 


C044 


MMDELTAX 


C045 MMDELTAY 


CQ46 DIAGTYPE 


C046 INTFLAG 


C047 


CLRVBLINT 


C048 CLRXYINT 


CO 50 TXTCLR 


C051 TXTSET 


C052 


MIXCLR 


C053 MIX SET 


CO 5 4 TXTPAGE1 


C055 TXTPAGE2 


CO 56 


LORES 


C057 HIRES 


CO 58 SETANO 


C059 GLRANO 


C05A 


SETAN1 


C05B CLRAN1 


C05C SETAN2 


C05D CLRAN2 


COSE 


SETAN3 


C05F CLRAN3 


C060 BUTN3 


C06l BUTNO 


C062 


BUTN1 


C063 BUTN2 


C064 PADDLO 


C068 STATEREG 


C06D TESTREG 


C06E CLRTM 


co6f entm 


C070 PTRIG 


C081 


ROMrN 


C083 LCBANK2 


C08B LCBANK1 


CFFF CLRROM 
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Appendix F 

Disassembler/ 
Mini-Assembler 
Opcodes 



"This appendix lists all of the 65C816 instructions and. ihe instruction formats that the 
disassembler uses to define the contents of the disassembly. You may wish to hand- 
assemble various short routines 'I his listing provides jfOU with 1 zciAv refetenCfl for 
the 65C816 instructions and addressing modes. Sometimes as the table begins a new 
alphabetic item in the name field, a line break is inserted for readability. For cases 
where the instructions are closely related to each other (such as branch instructions, 
push instructions, and pull instructions), the line break is omitted 

In die tabic that follows, the addressing modes of the processor are abbreviated as 
shown on the following page. 
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H^HH 



Abbreviation Tor 


Actual addressing 


addressing mod* 


mode represented 


- 


Immediate 


(a) 


Absolute indirect 


(a p x) 


Absolute indexed indirect 


(d) 


Direct indirect 


(d\y 


Direct indirect indexed 


(d r x) 


Direct indexed indirect 


(r,s).y 


Slack relative indirect indexed 


a 


Absolute 


a,x 


Absolute indexed (with x) 




Absolute indexed (with y) 


•\ c c 


Accumulator 


a] 


Absolute long 


al.x 


Absolute indexed long 


d 




d,x 


Direct indexed (with x) 


d.y 


Direct indexed (with y) 


i 


Implied 


r 


Program counter relative 


r.a 


Stack relative 


K 


Program counter relative long 


& 


Stack 


xya 


Block move 


Id] 


Direct indirect long 


Id],y 


Direct indirect indexed lone 
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Opcode 


Ma me 


Mode 


Bytes 


number 


ADC 


(d) 


2 


72 


ADC 


(d),y 


2 


71 


ADC 


<d,x) 


2 


61 


ADC 


(f.s).y 


2 


73 


ADC 


d 


2 


65 


ADC 


d,x 


2 


75 


ADC 


t,$ 


2 


63 


ADC 


Id] 


2 


67 


ADC 


[dj.y 


2 


77 


ADC 


# 


2 C3) 


69 


ADC 


a 


3 


6D 


ADC 


a,x 


3 


7D 


ADC 


a,y 


3 


79 


ADC 


al 


i 


6F 


ADC 


al,x 


4 


7F 


AND 


C<0 


2 


52 


AND 


Mi IV 


2 


31 


AND 


Cd,x) 


2 


21 


AND 


Cr,s>,y 


2 


33 


AND 


d 


2 


25 


AND 


d,x 


2 


35 


AND 


f.s 


2 


23 


AND 


Id] 


2 


27 


AND 


[dl.y 


2 


37 


AND 


* 


2 (3) 


29 


AND 


a 


3 


2D 


AND 


a,x 


3 


3D 


AND 


a,y 


3 


39 


AND 


al 


4 


2F 


AND 


al,x 


4 


3F 


ASL 


Ace 


l 


OA 


ASL 


d 


2 


06 


ASL 


d,x 


2 


16 


ASL 


a 


3 


0E 


ASL 


a,x 


J 


IE 


BCC 


r 


2 


90 


BCS 


r 


2 


BO 


BEQ 


r 


2 


H> 









Opcode 


Name 


Mode 


Bytes 


number 


BIT 


d 


2 


24 


BIT 


d,x 


2 


34 


BIT 


# 


2 (3) 


89 


BIT 


a 


3 


2C 


BIT 


a,x 


3 


3C 


BMI 


r 


2 


30 


BNE 


t 


2 


DO 


BPL 


r 


2 


10 


BRA 


r 


Z 


30 


BRK 


i 


2 


OQ 


BRL 


rl 


3 


82 


BVC 


r 


2 


50 


BVS 


r 


2 


-J 


CLC 


L 


1 


18 


CLD 


i 


1 


D8 


CL1 


i 


1 


58 


Cl.V 


i 


1 


BS 


CMP 


<d) 


2 


D2 


CMP 


(d),y 


2 


Dl 


CMP 


<d.x) 


Z 


CI 


CMP 


(r,s),y 


2 


D3 


CMP 


d 


2 


C5 


CMP 


d,x 


2 


D5 


CMP 


r,s 


2 


C3 


CMP 


Id] 


.' 


C7 


CMP 


[dl.y 


2 


D7 


CMP 


# 


2 G) 


C9 


CMP 


a 


3 


CD 


CMP 


a,x 


3 


DD 


CMP 


*.¥ 


3 


D9 


CMP 


al 


4 


CF 


CMP 


al,x 


4 


DF 


COP 


i 


2 


02 


CPX 


d 


2 


l"Vf 


CPX 


# 


2 C3) 


E0 


c:i'\ 


a 


3 


EC 
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Opcode 


Nam* 


Mode 


Bytes 


number 


CPY 


d 


2 


C4 


CPY 


#• 


2 (3) 


CO 


CPY 


a 


3 


CC 


DEC 


Ace 


1 


3A 


DEC 


d 


2 


C6 


DEC 


d,x 


2 


D6 


DEC 


a 


3 


CE 


DEC 


a,x 


J 


DE 


DI.X 


i 


1 


CA 


DEY 


i 


1 


88 


EOR 


Cd) 


2 


52 


EOR 


Cd),y 


2 


51 


EOR 


Cd,x) 


2 


41 


EOR 


Cr,s),y 


2 


53 


EOR 


d 


2 


45 


EOR 


d,x 


-: 


55 


EOR 


r.s 


2 


43 


EOR 


Id] 


2 


47 


EOR 


Jdl.y 


2 


57 


EOR 


* 


2 0) 


49 


EOR 


a 


3 


4D 


EOR 


a,x 


3 


5D 


EOR 


a.y 


3 


59 


EOR 


al 


4 


4F 


EOR 


al,x 


4 


5F 


INC 


Ace 


l 


1A 


INC 


d 


2 


E6 


INC 


d,x 


2 


- 


INC 


a 


' ; . 


EE 


INC 


a,x 


3 


FE 


I NX 


i 


i 


E8 


[NY 


i 


i 


C8 


JML 


(a) 


3 


DC 


IMP 


U:. 


3 


6C 


JMP 


Ca,x) 


3 


7C 


JMP 


a 


3 


4C 


JMP 


al 


i 


5C 









Opcode 




Nome 


Mode 


Byres 


number 




JSL 


al 


4 


22 




JSR 


Ca.x) 


3 


FC 




JSR 


a 


3 


20 




LDA 


Cd) 


2 


B2 




LDA 


Cd) t y 


2 


Bl 




LDA 


Cd,x) 


2 


Al 




LDA 


Cr,s),y 


2 


B3 




LDA 


d 


2 


A5 




LDA 


d,x 


.' 


B5 




LDA 


r,s 


2 


A3 




LDA 


Idl 


2 


A7 




LDA 


Idl.y 


2 


B7 




LDA 


# 


2 6) 


A9 




LDA 


a 


3 


AD 




LDA 


a,x 


3 


BD 


r ' 


LDA 


a.y 


3 


159 




LDA 


al 


4 


AF 




LDA 


al,x 


4 


BF 




LDX 


d 


2 


A6 




LDX 


d,y 


2 


156 




LDX 


# 


2 C3) 


A2 




LDX 


A 


3 


AE 




LDX 


a,y 


3 


BE 




LDY 


d 


2 


A4 




LDY 


d,x 


2 


B4 




LDY 


# 


2 G) 


AO 




LDY 


a 


3 


AC 




LDY 


a,x 


3 


BC 




LSI* 


Acc 


i 


4A 




LSI* 


d 


2 


46 




L5R 


d,x 


2 


56 




LSR 


a 


3 


4E 




l-SK 


a,x 


3 


5E 




MVN 


xya 


3 


54 




MVP 


xya 


3 


44 








EA 
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Opcode 








Opcode 




Nam* 


Mode 


Bytes 


number 


Name 


Mode 


Bytes 


number 




ORA 


Cd) 


2 


12 


ROR 


Ace 


1 


6A 




ORA 


Cd),y 


2 


11 


ROR 


d 


2 


66 




ORA 


Cd t x) 


2 


01 


ROR 


d.x 


2 


76 




ORA 


(r,s),y 


2 


13 


ROR 


a 


3 


6E 




ORA 


d 


2 


05 


ROR 


a,x 


S 


7E 




ORA 


d,x 


2 


15 


RT1 


E 


l 


40 




ORA 


r.s 


2 


03 












GRA 


[d] 


2 


07 


RTS 




1 
1 


6B 
60 




ORA 


(di.y 


2 


17 












ORA 


# 


2 (3) 


09 


SBC 


(d) 


2 


F2 




ORA 


i 


3 


0D 


SBC 


CdXy 


2 


F2 




ORA 


a,x 


3 


ID 


SBC 


Cd.x) 


2 


El 




ORA 


i,y 


3 


19 


SBC 


(r,s),y 


2 


F3 




ORA 


al 


4 


OF 


SBC 


d 


2 


E5 




ORA 


• :^l f X 


4 


IF 


SBC 


d.x 


2 


F5 




PEA 


S 


3 


F4 


SBC 


r .s 


2 


E3 




PEI 


s 


2 


D4 


SBC 


[d] 


2 


E7 




PER 


S 


3 


62 


SBC 

SBC 


[dl.y 

# 


2 
2 (3) 


F7 
E9 




PHA 


s 




48 












PHB 


s 




8B 


SBC 

SBC 


a 

a,x 


3 

.5 


ED 
FD 




PHD 


s 




OB 












piik 


s 




4B 


SB< 

SBC 


a.y 

al 


3 
4 


F9 




PHP 
PIIX 


s 

s 




08 
DA 


SBC 


al.x 


4 


FF 




PHY 


s 




5A 


SEC 


i 


1 


38 




PLA 


s 




68 


SED 
SFJ 


1 


i 

i 


F8 
78 




PLB 


s 




AB 


SEP 


- 


2 


E2 




PLD 
PLP 


s 




2B 












s 




28 


STA 


Cd) 


2 


92 




PLX 


s 




FA 


STA 


Cd),y 


2 


91 




PLY 


s 




7A 


STA 


Cd t x) 


2 


81 




REP 


#■ 




C2 


STA 
STA 


Cr,0.r 

d 


2 

2 


"3 
85 




ROL 


Ace 




2A 


STA 


d.x 


2 


95 




ROL 


d 




26 


STA 


r,s 


-' 


83 




ROL 


d,x 


: 


36 


STA 


Idl 


2 


87 




ROL 


a 


3 


2h 


STA 


Idl.y 


2 


97 




ROL 


a.x 


3 


u 


STA 

STA 


a 

a,x 


3 
3 


8D 
9D 












STA 


a.y 


3 


99 






■ 






STA 


al 


4 


8F 












STA 
STP 


.i 1 , K 

I 


4 
1 


9V 
DB 












ApBsrclls f i 3f&£§i 


mfel§r/Mlni-Ass§mfel! 


ir QpEeds s?? 





























Opcode 


Name 


Mode 


Bytes 


number 


STX 


■J 


2 


86 


STX 


d,Y 


J. 


96 


STX 


a 


3 


8E 


STY 


d 


J 


84 


STY 


d,x 


2 


94 


STY 


a 


3 


8C 


ST2 


d 


2 


64 


STZ 


d,x 


2 


74 


STZ 


a 


3 


9C 


STZ 


a,x 




9E 


TAX 


i 




AA 


TAY 


i 




A8 


TCD 


i 




5B 


TCS 


i 




IB 


TDC 


i 




7B 
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Appendix G 



The Control Panel 



The Control Panel firmware allows you to experiment with different system 
configurations and change the system time. You can also permanently store any 
changes in the battery-powered RAM (called Battery RAM), The Battery RAM is a 
Macintosh clock chip that has 256 bytes of battery-powered RAM for system- 
parameter storage. 

The Control Panel program is a ROM-resident hardware configuration program. It is 
invoked when the system is powered up if you press the Option key, An alternate means 
of invoking the Control Panel is to perform a cold start by pressing Control and the 
Option key at the same lime and then Reset. The Desk Manager can also call the 
Control Panel and affect the values specified in this appendix. 



Control Panel parameters 

Hie following are the selections and options available for each Control Panel menu. A 
mark (V) indicates the default value for each option. 
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^m 



■ 



mmm 



Printer port 

Sets up all related functions for the printer port (slot 1). Options are as follows: 



Opflon 

Device connect 

Line length 



Echo 

Buffering 

l-iaud 



Choices 

V Printer 
Modem 

V Unlimited 
40 

72 
80 
132 



Delete first LF after CR V No 

Yes 

Add LF after CR 



V Yes 
No 

V No 

Yes 

V No 

Yes 



75 

no 

134.5 
150 

300 

600 

1200 



2400 

3600 

4800 

7200 

V 9600 

19,200 



Option 




Choices 


Data bits 


V 


a 

6 
5 


Stop bits 


V 


1 


Parity 


V 


Odd 
Even 
None 


DCD handshake 


■, 


Yes 

No 


DSR/DTR handshake 


4 


Yes 

NO 


XON/XOFF handshake 


-1 


Yes 
No 
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Modem port 

Sets up all related functions for the modem port (slot 2). Options are as follows: 



Qpflon 




Choices 


Option 


Choices 


Device connected 


V 


Modem 
Printer 


Data bits 


V8 
7 


Line length 


,' 


Unlimited 

40 




6 
5 






72 


Stop bits 


V2 






80 




1 






132 


Parity 


Odd 


Delete first LF after CR 


•.' 


No 
Yes 




Even 
V None 


Add LF after CR 


J 


Yes 

No 


DCD handshake 


No 
t/ Yes 


Echo 


V 


No 

Yes 


DSR/DTK handshake 


V Yes 
No 


Buffering 


V 


No 
Yes 


XON/XOFF handshake 


Yes 
V No 


Baud 


V 


50 

75 

110 

134.5 

150 

300 

600 
1200 

1800 
2400 
3600 

.'i8f>i 

720Q 

19.200 
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WL 



Display 



Selects all video-specific options. Choosing Type automatically causes color or 
monochrome selections to appear on the rest ofihe screen. Options are as follows: 

Line option Choices 
Type ^ Color 



Columns 



Hertz 



Mono 

V 40 
SO 

V 60 
30 



Color/ 

monochrome 

oplJon* 

Text 
color 



Text 
background 



Choices 

{Color name is displayed!) 



Black 
Dark blue 
Purple 
Dark green 
Dark gray 
Medium blue 
Light blue 
Brown 



Orange 

Light gray- 
Pink 
Light green 
Yellow 
Aquamarine 
•4 White 



(.Color name is displayed!) 



Black 
Deep red 
Dark blue 
Purple 
Dark green 
Dark gray 
V Medium blue 
Light blue 



Brown 

Orange 

Lighl gr;i\ 

Pink 

Light green 

Yellow 

Aquamarine 

White 



Color/ 

monochrome 

options 

Border 
color 



Standard 
colors 



Choices 

(.Color name 
Black 

Deep red 
Dark blue 
Purple 
Dark green 
Dark gray 
t/ Medium blue 
Lighl blue 

No 
V Yes 



displayed!) 
Brown 
Orange 
Light gray 
Pink 

Lighl green 
Yellow 
Aquamarine 
White 



The Standard colors option indicates whether 
your chosen colors match Lhe Apple standard 
values. IT you select Yes, the current colors are 
switched to Apple standard colors, 



502 



Appendix G: The Control Panel 



Sound 

Allows system volume and pitch to be altered via an indicator bar. The default value is 
in the middle of each range. 



Speed 

Allows default system speed of either normal speed (1 MHz) or fast speeds (2,6/2.8 
RAM/ROM MHz). Available option* are as follows: 

Option Choices 

System speed V Fast 

Normal 



RAM dfsk 

Allows default amount of free RAM to be used for RAM disk. Options are as follows: 

Minimum free RAM for RAM disk: (minimum) 
Maximum free RAM for RAM disk; (maximum) 

Graduations between minimum and maximum are determined by adding or 
subtracting 32K from the RAM size that is displayed. Limited to zero or the largest 
selectable size. Default RAM disk size is bytes minimum, bytes maximum. RAM disk 
size ranges from bytes to largest selectable RAM disk size. 



The amount of free RAM (in kilobytes) for the RAM ilisk is displayed on the screen in 
Ihe format xxxxxK. Free RAM equals the total system RAM minus 256K. 

The current RAM disk size is also displayed on the screen. The current RAM disk slae 
can be determined by one of the RAM disk driver commands. 

The following message will be displayed on the screen: 

Total RAM In use: xxxxxK 

Total RAM in use equals total system RAM minus total free RAM. 

The total free RAM disk space will be displayed on the screen. You can determine the 
amount of total free RAM by calling the Memory Manager, 
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Slots 



Allows you to select either built-in device or peripheral card for slots I, 2, 5, 4, 5 r 6. 
and 7. Also allows you to select startup slot or to scan slots at startup time. Options 
available arc as follows: 



Option choices 

Slot 1 ^ Printer port 

Your card 

Slot 2 V Modem port 

Your card 

Slot 3 V Built-in text display 

Your card 

Slot 4 V Mouse port 

Your card 

Slot 5 V SmartPort 

Your card 

Slot 6 V Disk port 

Your card 



Option 
Slot 7 

Startup slot 



Choices 

Built-in AppleTalk 

V Your card 

V Scan 

1 
2 

3 
■■i 
5 
6 

7 

HAM disk 

ROM disk 



Options 

Allows you to select the keyboard layout, text display language, key repeal speed, and 
delay to key repeat to use- advanced features. Layouts and languages are displayed that 
correspond to the hardware. Layouts and languages noi available with your hardwa 
(keyboard micro and Mega II) are not displayed. The information about the layouts 
and languages that are available comes from the keyboard micro at power up i. 
Options arc as follows: 



Option 


Choice* 


Option 


Choices 


Display 


Chosen from Table G-l 


Repeat 


4 char/sec 


language 




speed 


8 char/sec 


Keyboard 


Chosen from Table G-l 




11 ch;i 


layout 






15 char/sec 
V 20 char/sec 


Keyboard 


VNo 




24 char/sec 


buffering 


Yes 




30 char/sec 
40 char/sec 






Repeal 


25 sec 






delay 


50 sec 

V ,75 sec 
1.00 sec 
No repeal 
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Option 




Choices 


Advanced features 




Double -dick 


1 uck = 1/60 sec 


Shift caps/ \ No 




time 




50 ticks (slow) 
40 ticks 
V 30 ticks 
20 ticks 
10 ticks QasO 


lowercase Yes 

Fast space/ V No 
delete keys Yes 

Dual speed "J Normal 
keys Fast 




Cursor 


(lash 


1 tick = 1/60 sec 


I ligh-speed V No 




rate 




ticks (no (lash) 
60 ticks 
V 30 licks 
15 licks 
10 ticks (fast) 


mouse Yes 




Table Gl 








Language options 








Number 


ASCII 


Number 


ASCII 


|| 


English (U.S.A.) 10 


Nnnish 


1 


English (U.K.) 11 


Portuguese 




2 


French 


12 


1 a mil 




3 


Danish 


13 


Hindi 




A 


Spanish 


14 


Tl 




5 


Italian 


15 


T2 




f. 


German 


16 


T3 




7 


Swedish 


17 


T4 




8 


Dvorak 


18 


T5 




: ; 


French Canadian 19 


T6 




A 


Flemish 


1A 


1.1 




B 


Hebrew 


IB 


L2 




c 


Japanese 


1C 


L3 




D 


Arabic 


ID 


L4 




E 


Greek 


IE 


L5 




F 


Turkish 


IF 


L6 




For the 


language options, items 0-7 are available lo control the display language. 




Items 8 


and 9 control the keyboard layout. 






(The keyboard microprocessor provides the 


pointer for the appropriate ASCII value 




listed in Table G-10 
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Clock 

Allows you to set the lime and dale and lime/date formats. Options are as follows: 



Option 


Choices 


Option 


Choices 


Month 


1-12 


Hour 


1-12 or 0-23 


Day 


1-31 




(depends on 






Formal selected) 


Year 


1904-2044 










Minute 


0-59 


Format 


V MM/DD/YY 








DD/MM/YY 


Second 


0-59 




YY/MM/DD 


Format 


V AM-PM 

24 -hour 



Quir 

Returns to calling application or, if called from keyboard, perform* a startup function. 



Battery-powered RAM 

The Battery RAM is a Macintosh clock chip thai I bytes of baltery-powered RAM 

used for system-parameter storage. The AppleTalk node number is stored in the 
Bauery RAM, set by the AppleTalk firmware. 

♦ Note: The Battery RAM is not for application program use. 

The Bauery RAM must Include encoded bytes for all options that can be selected from 
the Control Panel. Standard setup values are placed into Battery RAM during 
manufacturing However, the keyboard layout and display language are determined by 
the keyboard used. 

Items that can be changed by manufacturing and the Control Panel program can also 
be changed by your application program, however, only the Miscellaneous Tool Set 
Battery RAM routines or another Apple-approved utility program can make changes 
i Battery RAM, If the changing program is not an Apple-approved utility, Battery 
RAM will be severely damaged and the system will become inoperative. IF Bauery RAM 
is damaged and inoperative Cor the battery dies), the firmware will automatically use 
the Apple standard values lo bring up the system. The battery can be replaced, and 
you can enter the Control Panel program to restore the system to its prior 
configuration. 
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Control Panel at power-up 

At power- up, ihe Battery RAM is checksummed, ir the Battery HAM fails its checksum 
test, the system assumes a U.S. keyboard configuration and English language. Further, 
U.S. standard parameters are checksummed and moved to the Battery RAM storage 
buffer in bftnk SHI. The system continues running using US. standard parameters. 



Control Panel at power-i H 
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Appendix H 



Banks $E0 and $E1 



A special section of Apple IIGS memory is dedicated lo the Mega If chip. The Mega II. 
also called the Apple- H-on-a-chip, is a separate coprocessor lhat runs at 1 MHst and 
provides the display that the Apple IIGS produces on the video screen. 

To communicate with the Mega II, the Apple IIGS either writes df reedy into bank $E0 
or $E1 or enables a special soft switch, named shadouAng, When shadowing is 
enabled, whenever the Apple AGS writes Into bank $00 (or bank $01), the system 
automatically synchronizes with the Mega II and writes the same dala into bank $E0 (or 
bank $E1). 

Figure H-l depicts the layout of the memory in these banks of memory. Some of this 
memory is dedicated to display areas, some of it is reserved for firmware use, and 
some of it is declared as free space and is managed by the Memory Manager. 

Figure H-l shows the location of the various functions of Apple IIGS banks SEO and 
SET In the figure, ihe notation K means a decimal value of 1024 bytes, and the 
notation page means hex $100 bytes. 

* Mate In Figure H-l, the memory segments called free space are available through 
the Memory Manager only. 
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5E0 main language co/d 
$20 pages 
(BK reserved) 



Bonk $00 
S10 pages 
(4K reserved) 



Bank SOI 
$10 pages 
(4X reserved) 



I/O (always active) 



S6Q pages 

(24K free space) 



Double Hl-Res page two 
(S4000-S5FFF) 

Graphics 



Double Hi -Res page one 
(320OO-53FPF) 

Graphics 



S14 pages 

(5K reserved) 



Text Page 2 



Tex.? Page 



$4 PQQD5 

(IK reserved) 



Figure HI 

Memory map of banks $E0 and SET 



SFFFF 



SEOOO 



— SD03Q 



■SC000' 
■SAGOO- 
'S 8000- 

5 7000 



- S6DD0 
- $5000 ■ 
■ $4000 ■ 
■ 53000 ■ 
■52000' 

socao- 

S080Q - 
$0400 - 

SOCOC 



$E 1 aux language card 
$20 pages 
(8K reserved) 



Sank $00 
$10 pages 
(4K reserved) 



Bank $01 
$10 pages 

(4K reserved) 



I/O (always active) 



$20 pages 

(8K free space) 



Super Hi-Res 
C$6OO0-$9FFF) 

Graphics 



Double Hl-Res page rwo 
CS4000-SSFFF) 

Graphics 



Doubfe Hi-Res page one 
(S200D-S3FFF) 

Graphics 



$14 pages 
(6K reserved) 

Text Page 2 



Text Page 1 



5A pages 
(IK reserved) 
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Using banks $E0 and $E1 



You can use graphics memory located in memory banks $E0 and SEl or the free space 
via ihe Memory Manager-, however, you musl exercise caution to ensure thai you don't 
use areas thai are reserved for machine use. 



Free space 

Eighty hexadecimal pages, or |52K bytes, in the area labeled free space can be used; 
however, this area must be accessed through the Memory Manager. (The Memory 
Manager can be called through ihe Apple IIGS Toolbox.) If you uy to use this space 
without first catling the Memory Manager, you will cause a system failure. 

Video buffers not needed for screen display may be used for your applications. 

*> Note: Video buffers are used by firmware only for video displays because there is no 
way to determine which video modes are needed by your applications. 



Language-card area 

The language-card area is switched by the same soft switches used to switch Apple II 
simulation language cards in banks $00 and SOI. Before switching language-card banks 
Cor ROM for RAM or RAM for ROM), Ihe current configuration must be saved The 
configuration must be restored after your subroutine is finished accessing the switched 
area. 



Shadowing 

Ihe shadowing ability of the Apple tlGS can be used by applications to display overlay 
data on the screen. Normally, if an application wants to display an overlay on an 
existing screen, it musl save the data in the area that is overwritten. Because of the 
shadowing capabilities of the Apple IIGS, this task is simplified. 

When shadowing is turned on, you draw your original screen display into banks $00 
and $01. To display the overlay, turn shadowing off and write dirccdy into banks $E0 
and SEl. This affects only the display and not the original screen data that is also 
present in banks $00 and $01, When you are finished with the overlay, enable 
shadowing again and simply read and write the screen data (use MVN or MVP for 
speed) into the current screen area using banks $00 and $01. This will have no effect on 
banks $00 or $01, but il will restore the display to its appearance before the overlay 
data was written. 
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Glossary 



accumulator: The register In a computer's central 
processor or microprocessor where most 
computations are performed. 

ACIA: Abbreviation for Asynchronous 
Communications Interface Adopter, a type of 
communications IC used in some Apple 
computers. An ACIA converts data From parallel 
to serial form and vice versa. It handles seriaJ 
transmission and reception and RS-232-C signals 
under the control of its internal registers, which 
can be set and changed by firmware or software. 
Compare SCC. 

ADB: See Apple DeskTop Bus. 

address: A number that specifies the location of a 
single byte of memory. Addresses can be given as 
decimal or hexadecimal integers. The Apple IIGS 
has addresses ranging from to 16.777,2 15 
(decimal) or from $00 00 00 to SFF FF FF 
(hexadecimal). A complete address consists of a 
4-bit bank number C$00 to SFF) followed by a 16- 
bit address within that bank ($00 00 to SFF FF). 

Apple DeskTop Bus (ADB): A low-speed serial 
input port that supports the keyboard, the ADB 
mouse, and additional input devices, such as hand 
controls and graphics tablets. 

Apple key: A modifier key on the Apple IIGS 
keyboard, marked with both an Apple icon and a 
spinner, the icon used on the equivalent key on 
some Macintosh keyboards. It performs the same 
functions as the ci key on standard Apple II 
computers. 



AppleTalk: Apple's local-area network for 
Apple II and Macintosh personal computers and 
the LaserWriter and Imagcwnter II printers, Like 
the Macintosh, the Apple IIGS has the AppleTalk 
interface built in. 

AppleTalk connector: A piece of equipment 
consisting of a connection box, a short cable, and 
an 8- pin miniature DIN connector thai enables an 
Apple IIGS to be part of an AppleTalk network. 

Apple II: A family of computers, including the 
original Apple II, the Apple H Plus, the Apple Fie, 
the Apple lie, and the Apple IIgs. Compare 
standard Apple II. 

Apple IIGS Programmer's Workshop (APW>: 
The development environment for the Apple QGS 
computer. It consists of a set of programs that 
facilitate the writing, compiling, and debugging of 
Apple IIGS applications. 

APW: See Apple IIGS Programmer's 
Workshop. 

assembler: A program that produces object 
files (programs thai contain machine-language 
code) from source flies written in assembly 
language. The opposite of disassembler. 

background printing: Printing from one 
application while another application is running. 

bank: A 64K (65,536-byte) portion of the 
Apple IIGS internal memory. An individual bank is 
specified by the value of one of the 65C816 
microprocessor's bank registers. 
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bank-switched memory: On Apple II 

computers, that part of the language-card 
memory in which two 4K portions of memory 
share the same address range ($DOO0 to SDFFF). 

BASICOLJT: The routine that outputs a character 
when the 80-column firmware is active. 

Battery RAM: HAM memory on the Apple IlGS 
dock chip, A battery preserves the clock settings 
and the RAM contents when the power is off. 
Control Panel sellings are kept in the Battery RAM. 

baud rate: The rate at which serial data is 
transferred, measured in signal transitions per 
second, it takes approximately 10 signal 
transitions to transmit a single character. 

bit: A contraction of binary digit. The smallest 
unit of information a computer can hold. The 
value of a bit (1 or 0) represents a simple two-way 
choice, such as on or off, 

block: (1) A unit of data storage or transfer, 
typically 512 bytes, (2) A contiguous, page-aligned 
region of computer memory of arbitrary size, 
allocated by the Memory Manager. Also called a 

memory block. 

block device: A device thai transfers daia to or 
from a computer in multiples of one block (512 
bytes} of characters at a time. Disk drives are block 
devices. Also called block I/O device, 

boot: Another way to say start up. A computer 
boots by loading a program into memory from an 
external storage medium such as a disk. The word 
boot is shon for bootstrap had Starting up is 
often accomplished by first loading a small 
program, which then reads a larger program into 
memory. The program is said to "pull itself up by 
its own bootstraps. " 

buffer: A holding area in the computer's memory 
(for example, a print buffer) where information 
can be stored by one program or device and then 
read at a different rate by another. 



byte: A unit of information consisting of a 
sequence of 8 bits. A byte can take any value 
between and 255 ($0 and SFF hexadecimal). The 
value can represent an instruction, a number, a 
character, or a logical state. 

carry flag: A status bit in the microprocessor, 
used as an additional high-order bit with the 
accumulator bits in addition, subtraction, 
rotation, and shift opera lions. 

central processing unit (CPU); The part of the 
computer that performs the actual computations 
in machine language. See also microprocessor. 

character; Any symbol that has a widely 
understood meaning and thus can convey 
information. Some characters, such as tellers, 
numbers, and punctuation, can be displayed on 
the monitor screen and printed on a printer, Most 
characters are represented in the computer as 1- 
byte values. 

clamp: A memory location that contains the 
maximum and minimum excursion positions of 
the mouse cursor when the desktop is in use. 

CMOS: Acronym for complementary metal oxide 
semiconductor, one of several methods of making 
integrated circuits out of silicon. CMOS devices 
are characterized by low power consumption. 

controller card: A peripheral card that connects 
a device such as a printer or disk drive to a 
computer's main logic board and controls the 
operation of the device. 

Control Panel; A desk accessory that lets the 
user change certain system parameters, such as 
speaker volume, display colors, and configuration 
of slots and ports. 

control register; A special register that programs 
can read and write, similar to a soft switch. The 
control registers are specific locations in the I/O 
space ($Cxxx) in bank SEO, they are accessible 
From bank 500 if f/O shadowing is on. 
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Control-Reset A combination keystroke on 
Apple II computers that usuaJly causes an 
Applesoft BASIC program or command to stop 
immediately, 

COUTi The firmware entry point for ihe Apple II 
character-out pui subroutine. COUT is actually an 
I/O link located in RAM rather than in ROM, and 
so can be modified to contain the address of ihe 
presently active character output subroutine. 

COUT1: An entry point within the Apple II 
charaaer-ouipul subroutine. 

C3COUT1] AJso called BASICOUT, this is the 
routine that COUT jumps to when the 80-column 
firmware is active 

data: Information transferred to or from, or 
stored in, a computer or other mechanical 
communications or storage device 

I>CD: Abbreviation for Data Carrier Detect, a 

modem signal indicating that a communication 
connection has been established. 

Delete key: A key on the upper-right comer of 
the Apple He, Apple lie, and Apple IIGS 
keyboards that erases the character immediately 
preceding (to the left of) the cursor. Similar to the 
Macintosh Backspace key. 

delta; The difference from something the 
program already knows. For example, mouse 
moves are represented as deltas compared to 
previous mouse locations, The name comes from 
the way mathematicians use the Greek letter delta 
(A) to represent a difference. 

desk accessory; A small, special-purpose 
program available to the user regardless of which 
application is running. The Control Panel is an 

example or a desk accessory'. 

desktop; The visual interface between the 
computer and the user — the menu bar and the gray 
area on the screen. 



device; A piece of hardware used in conjunction 
with a computer and under the computer's 
control. Also called a peripheral device because 
such equipment is often physically separate from 
(but attached to) me computer. 

device driver: A program that manages the 
transfer of information between the computer and 
a peripheral device. 

Digital Oscillator Chip (DOC> An integrated 
Circuit in the Apple IIGS thai contains 32 digital 
oscillators, each of which can generate a sound 
from stored digital waveform data. 

DIN: Acronym for Deutsche Industrie Normal a 
European standards organization, 

DIN connector; A type of connector with 
multiple pins inside a round outer shield. 

direct page: A page (256 bytes) of bank $00 of 
Apple IIGS memory, any part of which can be 
addressed with a short (Tbytc) address because its 
high-order byte of the address is always $00 and its 

middle byte of the address is the value of the 
65C816 direct register. Coresident programs or 
routines can have their own direct pages at 
different locations, The direct page corresponds 
io ihe 6502 processor's zero page. The term direct 
page is often used informally to refer to any part of 
the lower portion of ihe dlrect-pagc/stadk space. 

direct-page/stack space: A portion of bank $00 
of Apple IIGS memory reserved for a program's 
direct page and stack. Initially, the 65C816 
processor's direct register contains the base 
address of the space, and its stack register 
contains ihe highest address. In use, the stack 
grows downward from the top of the direct- 
page/stack space, and the lower part of the space 
contains direct-page data. 

direct register: A hardware register in the 65C816 
processor that specifies the start of the direct page, 
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disassembler; A program that examines data in 
memory and interprets il as a set of assembly' 
language instructions. Assuming the data is object 
code, a disassembler gives the user the source 
code that could have generated thai ibject code. 

disk operating system,- An operating system 
whose principal (unction is to manage files and 
communication with one or more disk drives. 
DOS and ProDOS are two families of Apple II disk 
operating systems. 

Disk n drive: A type of disk drive made and sold 
by Apple Computer for use with the Apple n, 
Apple II Plus, and Apple He computers. It uses 
5.25-inch disks. 

DOC: See Digital Oscillator Chip. 

DOS: An Apple II disk operating system. Acronym 
for Disk Operating System. 

Double Hi-Res; A high-resolution graphics 
display mode on Apple II computers with al least 
128K of RAM, consisting of an array of points 560 
wide by 192 high with 16 colors. 

DSRi Abbreviation for Data Set Ready, a signal 
indicating that a modem has established a 
connection. 

DTRj Abbreviation for Data Terminal Ready, a 
signal indicating that a terminal is ready to 
transmit or receive data. 

c flag: One ol lag bits in the 65C816 

processor that programs use to control the 
processor's operating modes, The setting of the e 
flag determines whether the processor is in native 
mode or emulation mode. See also m flag and 
xflag. 

8-bit Apple lis Another way of saying standard 
Apple II; that is, any Apple II with an 8-bit 
microprocessor (6502 or 65C02). 

SQ-column text card: A peripheral card that 
allows the Apple II, Apple II Plus, and Apple lie 
computers to display text in 80 columns (in 
addition to the standard 40 columns). 



emulate: To operate in a way identical to a 
different system. For example, the 65C816 
microprocessor in the Apple IIGS can carry out all 
the instructions in a program originally written for 
an Apple II that uses a 6502 microprocessor, thus 
emulating the 6502. 

emulation mode: The 8-bit configuration of the 
65C816 processor in which the processor functions 
like a 6502 processor in all respects except clock 
speed. 

environment: The complete set of machine 

registers associated with a running program. 
Saving the environment allows a program 10 be 

red to its original operating mode with all of 
its registers intact as though nothing had 
happened. Saving and restoring an environment 
is most often associated with calling system 
functions or processing interrupts. 

error: The state of a computer after it has detected 
a fault in one or more commands sent to il. Also 
called error condition. 

escape code: A key sequence formed by pressing 
the Esc (Escape) key, followed by pressing another 
key. Escape codes arc used to control the video 
firmware. 

escape mode: The mode of video-firmware 
operation activated by pressing the Esc (Escape) 
key. It allows for moving the cursor, picking up 
characters from the screen, and performing other 
special operations. 

extended SmartPort call: A SmartPon call that 
allows data transfer to or from anywhere in the 
Apple IIGS system memory space. Compare 
standard SmartPort call. 

field: A string of ASCII characters or a value thai 
has a specific meaning to some program. Fields 
may be of fixed length or may be separated from 
Other Gelds by field delimiters. For example, each 
parameter In a segment header constitutes a field. 
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firmware; Programs siored permanently in 
ROM; most provide an interface to system 
hardware. Such programs (for example, the 
Monitor program) are built into the computer ai 
the factory. They can be executed at any time, but 
cannot be modified or erased from main 
memory. 

format: (n) The form in which information is 
organized or presented, (v) To divide a disk into 
tracks and sectors where information can be 
stored; synonymous with initialize. Blank disks 
must be formatted before the user can save 
information on them for the first time. 

frequency* The rate at which a repetitive event 
recurs, [n alternating current CAC) signals, the 
number of cycles per second. Frequency is usually 
expressed in hertz (cycles per second), 
kilohertz, or megahertz, 

GETLN: The firmware routine that a program calls 
lo obtain an entire line of characters from the 
currently active input device. 

GLUs Acronym for general logic unit, a class of 
custom integrated circuits used as interfaces 
between different parts of the computer. 

handshaking: The exchange of status 

inforrnauon between two data terminals used to 
control the transfer of data between them. The 
s:aiu. 1 Lni'urmatian can be Che state trf a signal 
connecting the two terminals, or it can be in the 
form of a character transmitted with the rest of the 
data, 

hertz (Hz): The unit of frequency of vibration or 
oscillation, defined as the number of cycles per 
second. Named for the physicist Heinrich Hertz. 
See also kilohertz and megahertz. 



hexadecimal: The base* 16 system of numbers, 
using the ten digits through 9 and the six letters A 
through F. Hexadecimal numbers can be 
converted easily and directly to binary form, 
because each hexadecimal digit corresponds to a 
sequence of 4 bits. In Apple manuals, 
hexadecimal numbers are usually preceded by a 
dollar sign C$). 

high order: The most significant part of a 
numerical quantity. In normal representation, the 
high-order bit of a binary value is in the leftmost 
position; likewise, the high-order byte of a binary 
word or longword quantity consists of the 
leftmost 8 bits. 

Hi-Res: A high- resolution graphics display mode 
00 the Apple II family of computers, consisting of 
an array of points 280 wide by 192 high with 6 
colors. 

Human Interface Guidelines: A set of software 
development guidelines designed by Apple 
Computer to support the desktop concept and lo 
promote uniform user interfaces in Apple U and 
Macintosh applications. 

icon: An image that graphically represents an 
object, a concept, or a message, 

index register; A register in a computer 
processor that holds an index for use in indexed 
addressing. The 6502 and 65C816 
microprocessors used in the Apple 11 family of 
computers have two index registers, called the X 
register and the Y register. 

initialize: See format (v). 

Intelligent device: A device containing a 
microprocessor and a program that allows the 
device to interpret data sent to it as commands 
that the device is to perform. 

interpreter: A program thai interprets its source 
files on a stalement-by-statement or character- 
by-characier basis. 
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Interrupt handler: A program, associated with a 
particular external device, that executes whenever 
that device sends an interrupt signal lo the 
computer. The Interrupt handler performs its tasks 
during the interrupt, then returns control to the 
computer so it may resume program execution, 

IRQ: A 65C816 signal line that, when activated, 
causes an interrupt request to be generated. 

IWM: Abbreviation for Integrated Woz Machine, 
the custom chip used in built-in disk ports on 
Apple computers. 

KEYIN: The firmware entry point that a program 
calls to obtain a keystroke from the currently active 
input device (normally the keyboard). 

kilobit: A unit of measurement, 1024 bits, 
commonly used in specifying the capacity of 
memory integrated circuits. Not to be confused 
with kilobyte, 

kilobyte; A unit of measurement, 1024 bytes, 
commonly used in specifying the capacity of 
memory or disk storage systems. 

kllohertz (kHz): A unit of measurement of 
frequency, equal to 1000 hertz. Compare 
megahertz. 

language-card memory: Memory with 
addresses between $DO00 and SFFTF on any 
Apple It-family computer. It includes two RAM 
banks in the $Dxxx space, called bank-switched 
memory. The language card was originally a 
peripheral card for the 48K Apple 11 or Apple II 
Plus computer that expanded the computer's 
memory capacity to 64K and provided space for 
an additional dialect of BASIC. 

last changeable location: The last location 
whose value the user inquired about through the 
Monitor. 



link: An area in memory that contains an address 
and a jump instruction. Programs are written to 
jump to the link address. Other programs can 
modify this address to make everything behave 
differently- COUT and KEYIN are examples of 
I/O links, 

longword: A double-length word. For the 
Apple IIGS, a long word is 32 bits (4 bytes) long. 

Lo-Res; The lowest resolution graphics display 
mode on the Apple II family of computers, 
consisting of an array of blocks 48 high by 40 wide 
with 16 colors. 

low order: The least significant part of a 
numerical quantity. In normal representation, the 
law-order bit of a binary number is in the 
rightmost position, likewise, the low-order byte of 
a binary' word or longwofd quantity consists of 
the rightmost 8 bits, 

megabit: A unit of measurement equal to 
1,048,576 (2 16 ) bits, or 1024 kilobits. Megabits are 
commonly used in specifying the capacity of 
memory integrated circuits. Not to be confused 
with megabyte. 

megabyte: A unit of measurement equal to 
1,048,576 (2^) bytes, or 1024 kilobytes. 

Megabytes are commonly used in specifying the 
capacity of memory or disk storage systems. 

megahertz (MHz): A unit of measurement of 
frequency, equal to 1,000,000 hertz. Compare 
kllohertz. 

Mega lis A custom large-scale integrated circuit 
thai incorporates most of the timing and control 
circuits of the standard Apple II. It addresses 128K 
of RAM organized as 64 K main and auxiliary banks 
and provides the standard Apple 11 video display 
modes, both text (40-column and 80-column) and 
graphics (Lo-Res, Hi-Res, and Double Hi-Res). 

memory block: See block (2). 
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Memory Manager: A program in the Apple IIGS 
Toolbox that manages memory use. The Memory 
Manager keeps uack of how much memory is 
available and allocates memory blocks to hold 
program segments or data. 

memory-mapped I/O: The method used for I/O 
operations in Apple U computers. Certain 
memory locations are attached to I/O devices, 
and I/O operations are just memory load and 
store instructions. 

m flag: One of three flag bits in the 65C816 
processor that programs use to control the 
processor's operating modes. In native mode, 
the setting of the m flag determines whether the 
accumulator is 8 or 16 bits wide. See also e flag 
and x flag. 

microprocessor: A central processing unit that is 
contained in a single integrated circuit, The 
Apple IIGS uses a 65C816 microprocessor. 

mini-assembler: A part of the Apple IIGS 
Monitor program mat allows the user to create 
small assembly-language test routines, See also 
assembler. 

Monitor program; A program built into lhe 
firmware of Apple U computers, used for directly 
inspecting or changing the contents of main 
memory and for operating the computer at the 

machine language Level. 

MOS: Acronym for metal oxide semiconductor, 
one of several methods of making integrated 
circuits. 

native mode: The 16 bit configuration of the 
65C816 microprocessor. 

flexl-changeafele location: The memory 
location that is next to have its value changed. 



NTSQ (1) Abbreviation for National Television 
Standards Committee, which defined the standard 
formal used for transmitting broadcast video 
signals in the United States, (2) The standard video 
format defined by the NTSC; also called 
composite because it combines all video 
information, including color, into a single signal. 

object file: The output from an assembler or a 
compiler, and the input to a linker. It contains 
machine-language inunctions. Also called object 
program or object code. Compare source flle. 

op code: See operation code, 

■-■'. A modifier key on some Apple II keyboards. 
On the Apple IIGS keyboard, the equivalent key is 
called simply the Apple key; it is marked with 
both an Apple icon and a spinner, the icon used 
on some Macintosh keyboards. 

operand: An item on which an operator (such as + 
or AND) acts. 

operation code: The part of a machine-language 
instruction thai specifies the operation lo be 
performed Often called op code, 

page: CI) A portion of memory 256 bytes long and 
beginning at an address that is an even multiple of 
256. Memory blocks whose starting addresses are 
an even multiple of 256 are said to be page 
aligned, (2) (usually capitalized) An area of main 
memory containing texi or graphic information 
being displayed on the screen, 

palette: The set of colors from which the user can 
choose a color to apply to a pixel on ihe screen, 

parameter: A value passed lo or from a function 
or other routine. 

parameter block: A set of contiguous memory 
locations set up by a calling program to pass 
parameters lo and receive results from an 
operaiing-systcm function that the program calls. 
Every call to SmartPort must include a pointer to a 
properly constructed parameter block. 
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parity bit: A bit thai is sometimes transmitted 
along with the olher bits that define a serial 
character. It is used to check the accuracy of the 
transmission of the character. Even parity means 
that the total number of 1 bits transmitted, 
including ihe parity bit itself, is even. Odd parity 
means that the total number is odd. The parity bit 
is generated individually for each character and 
checked, a character at a time, at the receiving 
end. 

peripheral device; See device. 

pixel: Short for picture element. The smallest dot 
that can be drawn on the screen. Also a location in 
video memory that corresponds to a point on the 
graphics screen when the viewing window includes 
that location. In the Macintosh display, each pixel 
can be either black or while, so it can be 
represented by a bit; thus, the display is said to be 
a bit map. In the Super Hi-Res display on ihe 
Apple IIGS, each pixel is represented by either 2 or 
4 bits, the display is not a bit map, but rather a 
pixel map. 

pixel map: A sel of values that represents the 
positions and states of the set of pixels making up 
an image. 

ProDOS! Acronym for Professional Disk 

Operating System, a family of disk operating 
systems developed for the Apple U family of 
computers. ProDOS includes both ProDOS 8 and 
ProDOS 16. 

ProDOS 8: A disk operating system developed for 
standard Apple II computers. It runs on 65Q2- 
series microprocessors and on the Apple IIGS 
when die 65C816 processor is in 6502 emulation 
mode. 

ProDOS 16; A disk operating system developed 
for 65C816 native- mode operation on the 
Apple IIGS. It is functionally similar to ProDOS 8, 
but more powerful. 



prompt: A message on ihe screen that a program 
provides when it needs a response from the user, A 
prompt is usually in the form of a symbol, a dialog 
box, or a menu of choices. 

Quagmire register: On the Apple IIGS, the 
name given to the 8 bits comprising the speed- 
control bit and the shadowing bits, From the 
Monitor program, the user can read from or write 
to the Quagmire register to access those bits, even 
though they are actually in separate registers. 

RAM: See random-access memory. 

RAM disk: A portion of RAM that appears to the 
operating system to be a disk volume. Files in a 
RAM disk can be accessed much faster than the 
same files on a disk. See also ROM disk. 

random-access memory (RAM): Memory in 

which information can be referred to in an 
arbitrary or random order. RAM usually means 
the pan of memory available for programs from a 
disk; the programs and other data are lost when 
ihe computer is turned off. (Technically, the read- 
only memory Is also random access, and what's 
called HAM should correcdy be leaned read-write 
memory.) Compare read-only memory. 

RDKEYj The firmware routine lhat a program uses 
to read a single keystroke from the keyboard. 

read-only memory (ROM): Memory whose 
contents can be read, but not changed; used for 
storing firmware. Information is placed into 
read-only memory once, during manufacture; it 
then remains there permanently, even when the 
computer's power is turned off. Compare 
random-access memory. 

recharge routine; The function that supplies 
data w ihe output device when background 
printing is taking place. 
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RGB: Abbreviation Tor red-green-blue. A method 
of displaying color video by transmitting the three 
primary colors as three separate signals. There are 
two ways of using RGB with computers: 771 RGB, 
which allows the color signals lo take on only a few 
discrete values; and analog RGB, which allows the 
color signals to take on any values between their 
upper and lower limits for a wide range of colors. 

ROM; See read-only memory. 

ROM disk: A feature of some operating systems 
that permits the use of ROM as a disk volume. 
Often used for making applications permanently 
resident, See also RAM disk, 

RS-232; A common standard for serial data 
communication interfaces, 

RS-422: A standard for serial data communication 
interfaces, different from [he HS-232 standard in 
its electrical characteristics and in its use of 
differential pairs for data signals. The serial ports 
on the Apple IIGS use RS-4122 devices modified so 
as to be compatible with RS-232 devices. 

SCC: Abbreviation for Serial Communications 

Controller, a type of communications IC used in 
the Apple IIGS. The SCC can run synchronous data 
transmission protocol and thus transmit data at 
faster rates than the AOA. 

screen holes: Locations in the text display buffer 
I ic ■:■;! Page 1) used for temporary storage either by 
I/O routines running in peripheral-card ROM or 
by firmware routines addressed as if they were in 
card ROM. Text Page 1 occupies memory from 
50400 to SQ7FF; the screen holes are locations in 
that area that are neither displayed nor modified 
by the display firmware. 

sector: See track. 



shadowing: The process whereby any changes 
made to one part of the Apple IIGS memory are 
automatically and simultaneously copied Into 
another part. When shadowing is on, information 
written to bank S00 or SOI is automatically copied 
into equivalent locations in bank $E0 or $E1. 
likewise, any changes to bank SEO or $E 1 are 
immediately reflected in bank 500 or SOL 

64K Apple II: Any standard Apple 11 that has at 
least 64 K of RAM. This includes the Apple lie, the 
Apple lie, and an Apple n or Apple D* Plus with 
48K of RAM and the language card installed. 

6502: The microprocessor used in the Apple II, 
the Apple II Plus, and early models of the 
Apple He. The 6502 is a MOS device with 8-bit data 
registers and 16-bit address registers. 

65C02: A CMOS version of the 6502, this is the 
microprocessor used in the Apple lie and the 
enhanced Apple He. 

65C816: The microprocessor used in the 

Apple IIGS. The 65C816 is a CMOS device with 16- 

bil data registers and 24-bit address registers. 

SmartPort: A set of firmware routines supporting 
multiple block devices connected to the 
Apple IIGS disk port. See also extended 
SmartPort call and standard SmartPort call- 
soft switch: A location in memory that produces 
a specific effect whenever its contents are read or 
written. 

source Hies An ASCII file consisting of 
instructions written in a particular language, such 
as Pascal or assembly language. An assembler or a 
compiler converts a source file into an object file. 

SSC: Abbreviation for Super Serial Card, a 
peripheral card that enables an Apple n to 
communicate with serial devices. 
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stack: A list in which entries are added (pushed) 
and removed (pulled) at one end onJy (the lop of 
the stack), causing them 10 be removed in last-in, 
first-out (LIFO) order The stack usually refers to 
the particular slack pointed to hy the 65C8l6's 
stack register. 

stack register; A hardware register in the 65C816 
processor thai contains the address of the top of 
the processor's stack, 

standard Apple lis Any computer Us the Apple II 
family except the Apple JIGS This includes the 
Apple H, the Apple 11 Plus, the Apple He, and the 
Apple lie, 

standard SmartPort call; A SmartPort call that 
allows data transfer to or from anywhere in 
standard Apple II memory, or the lowest 64K of 
Apple tics memory. Compare extended 
SmartPort calk 

start up: To get the system running. See boot. 

Super Hi-Res: A high resolution graphics display 
mode on the Apple u*GS, consisting of an array of 
points 320 wide by 200 high with Ifi colors or 640 
wide by 200 high with 16 colors (with restrictions) 

synthesizer: A hardware device capable of 
creating sound digitally and converting it into an 
analog waveform that can be heard. 

system disk: A disk that contains the operating 
system and other system software needed to run 
applications. 

system software: Trie components of a 
computer system that support application 
programs by managing system resources such as 
memory and I/O devices. 

terminal mode: The mode of operation in which 
the Apple lies acts like an intelligent terminal 

text window; The portion of the Apple n screen 
that is reserved for text At startup, the firmware 
initializes the entire display lo text However, 
applications can restrict text to any rectangular 
portion of the display. 
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tool: See tool set 

toolbox: A collection of built-in routines on the 
Apple FIGS that programs can call to perform 
many commonly needed functions. Functions 
within the toolbox are grouped into toolsets. 

tool set: A group of rel ited routines (usually in 
firmware) thai perform necessary function' 
provide programming convenience They are 
available to applications and system software, The 
Memory Manager, the System Loader, and 
QuickDraw II are tool sets. 

track: One of a series of concentric circles that are 
magnetically drawn on the recording surface of a 
disk when ihe disk is formatted. Tracks are further 
divided into sectors. 

vector: A location containing a value that, when 
added to a base address value, provides the 
address that is the entry point of a specific kind of 
routine. 

word: A group of bits that Is treated as a unit For 
rhr- Apple 1IGS, a word is 16 bits (2 byri'vi hri: 

x flag: Ore of three flag bits in the 650516 
processor that programs use to control the 
processor's operating modes In native mode, 

the setting of the x flag determines whether the 
index registers are 8 or 1 6 bits wide. See also e flag 
and m flag. 

XONj A special character (value $13) used for 
controlling the transfer of data between two pieces 
of equipment handshaking and XOFF. 

XOFF: A special character (value J 11) used for 
controlling the transfer of data between two pieces 
of equipment. When one piece of equipment 
receives an XOFF character from the other, it 
stops transmitting characters until it receives an 
SON, See also handshaking and XON. 

zero page: The first page (256 bytes) of memory 
in a standard Apple II computer (or in the. 
Apple IlGS when running a standard Apple 11 
program) Because the high-order byte of any 
address in this part of memory is zero, only a 
single byte is needed to specify a zero-page 
address Compare direct page. 
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ABORT 179 
Abort command 188 
ABORTMGRV 265 
accumulator 35 
accumulator mode 62 
ADB microcontroller. See 

Apple DeskTop Bus 

microcontroller 
addition 32-bit 
ADVANCE 240 
AMPERV 259 
apostrophe CO *i0, 64 

Apple DeskTop Bus connector 8 
Apple DeskTop Bus input devices 

10 
Apple DeskTop Bus microcontroller 
6. 183, 185-196 

commands 188-195 

status byte 196 
Apple 35 disk drive 117, 133, 135 

SmartPort calls 138-141 
APPLE1I 237 
Apple lie 11 
Apple lie Plus 222 
Apple IIGS 

boot/scan sequence 17 

detached keyboard 10 

SQ-column display 71 

firmware 2-6 

40 -column display 71 

interrupts 16 

I/O expansion slots 11 

I/O ports 1 1 

memory addresses 21 

memory space 9 

microprocessor 8-9 

Monitor. See system Monitor 

program operation levels 4 

sound system 10 



112 

Super Hi-Res display 9-10 

technical manuals 216-221 

Toolbox 2, 218, 3 10 
Apple IIGS Disk II 

Firmware 5 

I/O port characteristics 111 

SmaitPort interactions 158 

support 109-112 
Applesoft BASIC 2, 43, 74, 87, 

112, 178 
Apple Super Serial Card (SSQ 82 
AppteTalk 3, 8, 15, 17, 82. 98, 
173 

interrupts 180 
A register 18, 35 

changing 60 

system interrupt handler 181 
arrow keys 72 

ASCII 25, 26, 29, 51, 67, 86, 
123. 152 

fillers 31 

nip 30, 64 

input mode 30 

literal 30, 64 
assembly language 

mouse routines 202, 211-213 

Pascal protocol 93-94 
at sign C©) 226 
AUXMOVE 260 



Back Arrow key 75 
background printing 97-98 
backslash CO 75 
Backspace key 70, 75 
BADBLOCK 156 
BADCMD 156 
BADCTL 156 
BADCTLPARM 156 



BADPCNT 156 

rJADUNIT 156 
bank 500 12, 15 

firmware entry points 224-257 

page Fx vectors 262-263 

page 3 routines 260-261 

page 3 vectors 259 

running a program in 49, 65 
bank/address 21. 22, 26, 29, 32, 

64 
bank $E0 308-310 
bank $E1 308-310 

vectors 264-265 
BASCALC 239 

BASIC 48, 51. 74. 75. 82, 83, 86, 
87, 90, 112 

command 43 

interface 93 

mouse programs 206-206 

mouse routines 203 
BASIC! N 70-73 
BASfdNPUT 209 
BAS1COUT 70, 73, 76-78, 80 
BASICOUTPUT 209 
Battery RAM 299, 306 
baud rate 88 

BD command 96, 97, 183 
BELL 253 
BELLI 239 
BELL 1,2 239 
BELL2 240 
BELLVECTOR 270 
B1NITENTRY 209 
boot-failure screen 17 
boot/scan sequence 17 
BREAK 233 
Break (BRK) 36, 183 
BREAK VECTOR 270 
B register 18, 35 
BRK 179 
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UttKV 259 

BS 241 

Buffering Enable 83 

KR 156 
bus residents 157 
button 1 status 2(M-205 



Call statement 20 

caret CD 53. 55 

carriage return 59 , 75, 83 

CLAMPMOU5E 209. 213 

Clear Modes command 189 

CLEARMOUSE 209, 212 

CLEOLZ 79 

clock 306 

dock chip interrupts 180 

Close call 5, 131-132 

CLREOL 79, 243 

CLREOLZ 243 

CLREOP 79, 242 

CI.RSCR 79, 226 

CLRTOP 79, 227 

cold start 65, 112, 178, 234 

colon CO 28. 29, 40, 51, 52. 64 

color graphics 10 

command characters 87 

communications mode 87 

printer mode 87 

terminal mode 91-92 
command packets, SmartPort 159, 

166-167 
command strings 87 
communications mode 83 

command character 87 

commands 91-.92 
Continue BASIC command 43 
Conlrol-A 64 
Control! 77 
Control- \ 77 
Control-] 77 
Control-. 77 
Control* 77 
Control -A 87 
Control -D 43, 65 
Control -C 43, 65 
Control call 129-130 



control characters 73, 76-78 

suppressing 90 
Control -E 60, 77 
Con<*oi-F 77 
Control-C 77 
Control-H 77 
Conuol-I 87 
Conttol-J 77 

. WUULJJ-IT OH, T-f 

Conuol-L 77 
Conuol-M 77 
Conuol-N 77 
Control-O 77 
Conlrol-P 40, 64 
Control Panel 3. 40, 75, 82, 83, 
86, 90, 93, 97, HO, 112, 117, 
130, 299-307 
Gontrol-Q 77 
Conlrol-R 66, 77 
Control-Reset 43, 46, 112 
Control- 5 77 
Control-T 64 
Control-U 77 
Comrol-V 77 
Coniiol-W 77, 87 
Control-X 58, 75, 77, 247 
Control-Y 47, 65, 77 
COP 36, 179 
COPMGRV 265 

copy-protection engineer CCPE) 
tools 144-145 
COPYRIGHT 209 
COLT 70, 71, 75, 76, 79, 249 
COUT1 64, 70, 74, 76-80, 249 
COUT subroutine 39 
COLTZ 249 
CPE (copy-protection engineer) 

tools 144-145 
CR 242 

C register 18, 35 
CROLTT 79, 248 
CROUT1 247 
C3COUT1 64, 70, 76-78 
CTRLWECTOR 274 
CUP DATE 269 
cursor 71 

changing 4 1, 64 

control 72 
keys 10 



data bank register 13. 16, 35, 92 

changing 6l 

system interrupt handler 181 

data buffer pointer 126-127 

data byte encoding table 164 

data carrier detect (DCD) 84 

data format R8 

data set ready (UbR) fcrt-8>, t> 

data terminal ready (DTR) 84-85, 

95 
date 

changing 64 
displaying 40, 63 
DBR register 11, 13, 35 
DCB (device control block) 123. 

130 
DCD (data carrier detect) 84 
debugging 48 
DECBUSYFLG 270 
decimal numbers, convening 41, 

65 
Delete hey 75 
delta 199 
Desk Manager 180 
device control block (DCB) 123. 

130 
device mapping 117-119 
DEVSPEC 156 
DIAGMOUSE 209 
diagnostic routines 3 
DIG 256 

Digital Oscillator Chip (DOC) 10 
direct page 12, 15 
direct-page register 13 
direct register, system interrupt 

handler 181 
Disable Device SRQ command 195 
disassembler 55-56 
opcodes 293-298 
Disk II firmware 5 
D1SKSW 156 
DISPATCH 1 264 
DISPATCH 2 264 
dispatch address 1 15 
display 302 
division, 32-bit 42 
DOC (Digital Oscillator Chip) 10 
dollar sign ($) 54 
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DOS 70, 110 


Esc-Control- Q 73 


GETLN0 247 




DOS 3.3 43 


Esc D 73 


GETLN 1 247 




Download 143 


Esc E 73 


GETLNZ 246 




D register 11, 35 


Esc 8 73 


Gei.ModeBits 95, 100 




changing 60 


Esc F 73 


GETNUM 256 




DSR Cdata set ready) 84-85, 95 


E&C 4 73 


GetOutRuffer 97, 98, 101 




DTR (data terminal ready) 84-85, 


Ese 1 73 


GetPorlSlat 104 




95 


Esc J 73 


GelSCG 10-1 




DuoDtsk 110 


Esc K 73 


Get Version Number command 






Esc M 73 


192 




E 


Event Manager 75, 183 


GLU chip 183, 186, 199 




Examine instruction 37 


GO 252 




EABORT 177, 263 


exclamation point ( " J 52 


Go command 36, 49 




EBRKIRQ 263 


Execute 142 


grsphk 5 display raode£ 10 




echo 91 




graphics tablets 10 




ECOP 177, 263 








ED command 91 


F 






EG command 91 


FD command 90 


H 




c llag 37 


FD10 245 


handshaking 84-135 




Eject 138, 142 


Fill Memory- command 59 


protocol 89 




emulation mode 9, 14, 37-38, 56, 


filter mask, changing 63 


1 tFADR 244 
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firmware. See also specific 


hexadecimal 21, 25, 26, 32, 53, 




accumulator 18 


type 


115. 116 




changing 62 


entry points 224-257 


math 42 




code 15 


ID bytes 222-223 


numbers, converting 41, 65 




stack 13 


I/O routines 11-16, 79 


HL1NE 79, 226 




EMULSTACK 13 


flag-modification commands 38 


HOME 79, 242 




Enable Device SRQ command 194 


flags 8, 12, 14, 16, 35-38 


HOMEMOUSE 209, 213 




enable line formatting 89 


examining and changing 36-38 


hook table 145 




ENM1 263 


restoring 66 






Ensoniq chip interrupts 180 


flashing text 78 


■ 




environment 8, 36 


flip ASCII 30, 64 


I 




firmware routines 11-16 


Flush command 6, 180 


IDROUTtNE 250 




resetting 66 


Flush Device Buffer command 195 


immediate mode 56-57 




restoring 14 


FlushlnQ ucuc 102 


INCBU5YFI.G 270 




system interrupt handler 181 


Flush Keyboard BufTer command 


index mode, changing 62 




equal sign <=) 37 


188 


IN1T 236 




ERESET 263 


FlushOutQueue 102 


Inil call 130 




error codes, SmartPort 156 


Format 5, 128, 139, 147 


1NITMOUSE 203, 209 




error status register 95 


free space 308, 310 


INPORT 251 




Esc A 73 




input buffer 46, 75, 91 




Esc ® 73 


G 


input links, redirecting 64 




escape codes 72, 73 


input routines 71-75 




Escape key 72 


GBA5CALC 227 


InQStatus 96, 103 




escape mode 71, 72 


GelDTR 1 05 


INSDS1 2 229 




Esc B 73 


GET816LEN 230 


INSDS2 229 




Esc C 73 


n Buffer 101 


INSTDSP 230 




Esc-Control D 73 


Getlntlnfo 96. 105, 184 


Integer BASIC 43, 74 




Esc-Conlrol-E 73 


GETLN 21, 71, 74-75. 79, 246 
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Integrated Woz Machine 0WM> chip 

5. 110-111 
Intelligent devices 5 
interrupt 15, 16. 95, 96-97, 171 

priorities 177-180 

processing 181-182 

vectors 177 
interrupt handler 16 

built-in 172-174 

firmware 6, 169-184 
Interrupt Request (IRQ) line 171 
INTMGRV 264 
Inverse command 39, 63 
inverse text 78 
inverse video 39, 71 
IOERROR 156 
I/O links 70 
I/O port 5 11 4 
lORTS 254 
IRQ 180 

IRQAPTALK 266 
IRQDSKACC 268 
IRQ.EXT 269 
IRQ, FLUSH 269 
1RQ.KBD 268 
IRQ. MICRO 269 
IRQ MOUSI 3 
IRQ-1SEC 269 
IRQ.OTHER 269 
IRQ.QTR 268 
IRQ RESPONSE 268 
IRQ.SCAN 267 
IRQ-SERIAL 266 
IRQ.SOUND 267 
IRQ.SRQ 268 
IRQ.VBL 267 
IRQLOC 259 
tHQVECT 177 

fWM (Integrated Woz. Machine) chip 
5, 110-111 



.IMP instruction 47, 50, 65, 66, 
145 

joystick 10 

J SI.. See jump to subroutine long 
JSR. See jump to subroutine 
jump to subroutine QSR) 12, 14, 
47, 49, 49, 50, 114 



jump to subroutine long QSL) 12, 
14, 50, 98, 152 



K13DWA1T 238 

keyboard 10, 40, 43, 71, 72 
input buffering 75 
interrupts 180 
language codes 190 

Keyboard command 40 

KEVIN 70, 71-72, 79, 245 

K register 35 



language card 16 

area 310 

bank 35, 56, 63 
language options 305 
last-opened location 25, 26 
less-than character C<) 31, 34 
LF 242 
line feed 83 

automatic 90 

masking 91 
line length 89 
"LIST 250 
Listen 6 

List instruction 53, 55, 66 
literal ASCII 30. 64 
local-area network. See 
ApplcTalk 

M 

machine- language programs 48-50 
machine registers 12 
machine state .36 

changing 6l 
mailbox registers 186 
mark table 144-145 
Masking Enable 83 
Mega 11 chip 308 
memory 9 

changing 28-31, 64 

comparing data 33 

moving data 31-32 

searching for bytes 34 



memory dump 27 
memory locations 

changing 28-30 

displaying 58 

examining 26-27 

text window 80 
Memory Manager 9, 15, 308, 310 
memory range 

display 27 

filling 34 

terminating 58 
m flag 37 
microprocessor. See specific 

type 
mini-assembler 51-55, 74 

instruction formats 54-55 

opcodes 293*298 
modem communications 84 
modem port 301 
HON 255 

Mon itor. See system Monitor 
Monitor command 49 
M ruLor firmware 1 
MONZ 255 
MONZ2 255 
MONZ4 256 
mouse 

interrupts 180. 183 

position clamps 201 

position data 199-201 
mouse firmware 6, 197-213 

calls 209 

using 202-205 
mouse programs, BASIC 206-208 
MOVE 250 

Move command 31-32, 45, 59 
M register 36 
M5GPOINTER 275 
MSl.OT 266 
multiplication, 32-bit 42 
music 10 



N 

N ABORT 177, 262 

native mode 9, 14, 56 
accumulator 16 
stack pointer 13, 14, 15 

N BREAK 177, 262 
NCOP 177. 262 
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next -changeable location 25, 26 

NIRQ 177, 262 

.M.MI 177, 178, 259 

N'NMI 177, 262 

NODRIVE 156 

NOINT 156 

NONFATAL 156 

Normal command 39, 44, 63 

normal video 39 

NOWR1TE 156 

numeric keypad 10 

NXTA1 244 

NXTA4 244 

NXTCHAR 257 

NXTCOL 227 



OFFLINE 156 

OLDBRK 233 

OLDISQ 233 

OLDRST 255 

opcodes 56-57, 293-298 

Open call 5, 131 

options 304-305 

OPTMOUSE 209 

OtJTPORT 252 

output links, redireciing 64 

output routines 76-78 

OutQStarus 96, 103 

P 

palettes 10 

parity 89 

Pascal 48, 82, 86, 97, 110, 210 

Pascal 1.1 93 

Pattern Search command 34, 59 

PBH register 11, 35 

PCADJ 232 

period CO 26, 27 

picture clement. See pixel 
Pinil 209. 210 
pixel 10 

PLOT 79, 225 

PLOT1 225 

plus sign CO 71, 72 

Pol] Device command r>- 

POSMOLJ5E 209, 211, 213 

PRA1 248 



PRBL2 79, 231 
PRBI.NK 231 
PRBVTE 79, 248 
PRead 209, 210 
PREAD 235 
PREAD4 235 
P register 35 
PRERR 253 
PRilEX 79, 248 
Printer command 40 
printer mode 83 

command character 87 

commands 88-90 
printer port 300 
PRNTAX 79, 230 
PRNTX 231 
PRNTYX 230 
processor Status 

changing 6l 

register 37 

system interrupt handler 181 
ProDOS 43, 70, 110, 114. 115, 

130 
ProDOS 8 117, 220 
ProDOS 16 117, 220 
program bank register 17, 35 

system interrupt handler 181 
program counter 51 
program operation levels 4 
program register, changing 6l 
prompt 74 
PROMPT 247 
prompt character 

C-) 20, 26, 74 

CD 74 

CO 52, 74 

CO 74 

C?) 74 
PR016MLI 274 
pseud oregistere 8, 16 
PStatus 209, 210 

PWREDUP 259 
PWrite 209, 210 
PWRUP 234 



Q 

Q register 36 

Quagmire register 16, 36 

Quagmire state, changing 62 



quarter-second timer interrupts 

180 
question mark (?) 74 
quit 306 

Quit Monitor command 43, 65 
quotation mark CO 34, 52 



RAM disk 17, 110, 114, 117, 234, 

303 
random-nu ruber generator 72 
R command 90 
RdAddr 146 
RDCHAR 246 
RDKEY 70, 71, 79, 244 
RDKEY1 245 
READ 253 

Read Address Field 139 
Read Available Character Sets 

command 193 
Read Available Keyboard Layouts 

command 193 
ReadBlock call 5, 126 
Read call 132-133 
Read and dear Error Byte 

command 192 
Read Configuration Bytes command 

192 
ReadData 146 
Read Microcontroller Memory 

command 191 
Read Modes Byte command 191 
READMQUSE 183, 203, 209, 212 
read-only memory 20 
Receive Bytes command 194 
Recharge routine 97. 98 
REGDSP 235 

register addresses, mouse 200 
register-display command 22 
register-modification commands 38 

registers 8, 12-18. 35-38 

examining 60 

examining and changing 36-38 

restoring 66 
RESERVED 156 
RESET 177. 178, 234 
Reset ADB command 194 
Reset! look 14 
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Reset Keyboard Microcontroller 

command 188 
ResetMark 141 

Reset Lhe System command 193 
RESTORE 254 
Resume command 50, 179 
return Tram subroutine CRTS) 49, 

65 
return from subroutine long (RTL) 

14 
Retype key 75 
ROM (read only memory) 20 
ROM disk 17, 110, 114, 117, 234 
driver 152-155 
passing parameters 152-153 
ROM Tor 154-155 
RTHI, 235 
RTL (return from subroutine long} 

M 
KTS (return from subroutine) 49, 

65 



SAVE 254 

scan -line interrupts 180 

Scrap Manager 180 

screen hales 203 

SCRN 79, 228 

SCROLL 243 

SCSI (Small Computer System 

Interface) 115 
Seek 139, 147 

Send ADB Keycode command 193 
Send command 97 
SendQueue 97, 98, 103 
Sc-ndRcsct 6 
serial-port firmware 5, 81-108 

background printing 97-98 

buffering 95-96 

compatibility 82 

error handling 95 

extended interface 99 

handshaking 84-85 

interrupt notification 96-97 

operating commands 86-92 

operating modes 83 

programming 92-94 



SI rial port interrupts 180, 183-184 

SEKVEMOUSE 202, 209, 212 

SetAddress 143 

SLTCOL 79, 225, 226, 228 

Set Configuration Bytes command 

190 
SciDTR 105 
SETGR 236 
Sell look 138-139 
SellnBuffer 95, 102 
Setlnierlcave 141 
Scllntlnro 96, 106, 184 
SETINV 251 
SETKBD 251 
SciMark 140-141 
SeiModeBiu 95, 97, 100-101 
Set Modes command 189 
SfcTMOUSE 209, 211 
SETNORM 251 
SelOulBuffer 95. 97. 102 
SETPWRC 237 

CC 105 
5etSides 141 
SETDTT 236 
SETVBLCNTS 209 
SETVin 252 
SETWND 236 
SETWND2 237 
shadowing 308, 310 
Shadow register 16 
6805 AppleMouse microprocessor 

card 213 
6502 microprocessor 8 
65C816 assembly language 54 
65C816 microprocessor 8-9 
Apple Desktop Bus 

microcontroller 186 
emulation mode 14 
execution speeds 9 
indexed instmciions 17 
modes 9 
slash CO 22, 40 
SLOOP 234 
slow 304 
Small Computer System Interface 

(SCSI) 115 



SmartPort 110 

assignment of unit numbers 
117-119. 157-158 

call parameters 1 16 
ml How 159-165 

DLsk II interactions 158 

dispatch address 115 

error codes 156 

extended commands 137 

issuing a call 120-121 

locating 114-115 

read protocol t6l 

standard commands 136 

write protocol 162 
SmartPort bus 133, 157-165 

packet contents 164 

packet format 163 
SmartPort calls 121-137 

device-specific 138 

specific to Apple 3,5 disk drive 
138-141 

specific to UniDisk 3.5 142-143 
SmartPort firmware 5, 17, 113-165 
50FTEV 259 
soft switches 277-290 
sound 303 
Speed register 16 
S register 11, 35 
SRQ 180 

SSC (Apple Super Serial Card) 82 
stack 1 5 
stack pointer 13-15, 35 

changing 6l 
STARITIME 209 
Status calls 121-125 
status code error 122 
status register 56 
Step command 50, 66 
STEP VECTOR 271 
STORADV 240 
Store command 44 
subtraction 12-bll 42 
Super Hi-Res display 8, 9-10 
symbol table 291. 292 
Sync command 191 
SYSDMCRV 265 
system interrupts 175-180 
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system Monitor 
command syntax 21 
command types 21-24 
creating commands 47 
80-coJumn mode 25-26 
Tilling memory 45 
firmware 4, 19-07 
40-eolumn mode 25 
invoking 20 

memory commands 25-34 
miscellaneous commands 39-43 
multiple commands 44 
repeating commands 46 



T 

tabbing 92 

TABV 237 

Talk 6 

terminal mode 83 

command character 91-92 
TEXT2COPY 232 
text display, changing 63 
text window 80 
lime 

changing 64 

displaying 40, 63 
TIMEDATA 209 
TOBEUMSETUP 273 
TOCTRL PANEL 273 
toolbox routines 43 
tool error number 67 
Tool Locator 43, 55, 67 
TOPR1NTM5GB 273 
TOPRINTM5G16 274 
TOREADBR 272 
TOREADTIMJ- 273 
TOSUB 247 
TOTEXTPG2DA 274 
TOWRITEBR 272 
TOWRITETJME 272 
Trace llhiiiiijiiij jo, Od 
TRACEVECTOR 271 
Transmit num Bytes command 

194 
Transmit Two Bytes command 195 



UDTSPATCH 1 264 
UDISPATCII2 264 

underscore (_) 41, 67, 83 

UniDiskStat 143 

UniDlsk 3.5 110, 117, 133, 135 
interna] functions 144-145 
internal routines 146-149 
memory allocation 150-151 
SmanPort calls 142-143 

UP 241 

User command 47 

user vector 6$ 

USRADR 259 



V 

vectors 70, 149, 258-275 

Verify 33, 45, 59, 140, 148 

VERSION 238 

vertical blanking signal 180, 183 

video firmware 5, 69-80 

VIDOUT 240 

VIDWAIT 238 

VLINE 79, 226 

VTAB 241 

VTABZ 79, 241 



W 

WAIT 243 

wzrm start 65, 112, 178 
windows 219 
WRITE 253 
WriteBlock call 5, 127 
Write call 134-135 
WriteData 147 
Write Data Field 139 
Write Microcontroller Memory 

command 191 
Write Track 139-140 
irk 118 



X 

XBA 18 

X command 50 

XFER 261 

x flag 37 

XOFF 85, 89, 95 

XON 85, 89, 95 

X register 35, 74, 98, 121 

changing 60 

system interrupt handler 181 



Y 

Y register 35, 98, 121 
changing 60 
system interrupt handler 181 



Zap command 34, 87 
zero page 12, 15 
ZIDBYTE 239 
ZIDBYTE2 238 
Zilog Serial Communications 

Controller chip 82 
ZMODE 257 
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THE APPLE PUBLISHING SYSTEM 

This Apple manual was written, 
edited, and composed on a 
desktop publishing system using 
the Apple Macintosh™ Plus and 
Microsoft Word. Proof and 
final pages were created on the 
Apple LaserWriter* Plus, 
POSTSCRIPT™, the LaserWriter 
page-description language, was 
developed by Adobe Systems 
Incorporated, 

Text type is ITC Garamond* 
(a downloadable foot distributed 
by Adobe Systems), Display type 
is ITC Avant Garde Gothic® 
Bullets are ITC Zapf Dingbats®. 
Program listings are set in Apple 
Courier, a monospaced font. 





The Apple Technical library 

The Official Publications from 
Apple Computer, Inc 

The Apple Technical Library offers programmers, 
developers, and enthusiasts the most complete 
technical information available on Apple" 
computers, peripherals, and software. The library 
o insists of technical manuals for the Apple II (amity 
of computers, the Macintosh™ EunUydfcampmeiSb 
and their key peripherals and programming 
environmui'v 

Manuals for the Apple fl family include technical 
references to the Apple De, Apple He, and Apple 
lies" computers, with detailed descriptions of the 
hardware, firmware, PmDOS* operating systems, 
and built-in programming tools that programmers 
and developers can draw upon. In addition to a 
technical introduction and programmer's guide to 
the Apple litis, itiere are tutorials and referenu 
Applesoft BASIC and Instant Pascal programmers. 

Manuals for the Macintosh family, known collectively 
as the Inside Macintosh Library, provide complete 
technical references to the Macintosh 512K, 
Macintosh S12K. Enhanced, Macintosh Plus, Macintosh 
si:, and Macintosh D computers. Individual volumes 
provide technical introductions and programmer's 
guides no the Macintosh, as well as detailed 
information on hardware, firmware, system 
software, and programming tools. The Inside 
Macintosh Library oners the most detailed and 
complete si juree of information available for the 
Macintosh family of computers, 

Tn addition, titles in the Apple Technical Library offer 
references to the wide range of important printers, 
communicate >ns standards, and prn grairnnig g 
environments— such as die Standard Apple 
Numerics Environment ( SANE" )-to help 
programmers and experienced users get tire most 
out of their computer systems. 



The Official Publication from Apple Computer, Inc. 

Now programmers and designee have a comprehensm i die inner 

workings of die popular Apple lies™ computer. 

With its impressive 256K base memory, expandable to well over ^ megabytes, and 
its enhanced color graphics and sound capabilities , die- Apple Dgs is destined to 
become die new standard in the educational computer market, and die dxx 
software developers. As the Apple Has user base grows, more and more 
programmers need the important technical information found only in this manual. 

The Appk Hgs Firmware Reference the companion volume to the Appii 
Ihmiu are Reference is Apples definitive guide for as.sembly-langiiage pit >grarnmers 
and hardware developers working with the Apple Qcs In a single volume, it 
provides an extensive description of the internal operations of the machine and 
its the latest information about the firmware fari lities that the Dgs provides. 

The manual begins with an overview of Apple Qcs firmware. Then, in detaii, it tells 
how to use the firmware tu access the systems monitor, mini-assembler, 

disassembler, keyboard, mouse, video display serial rx iris, and di.sk drives. 

Detailed appendixes contain summary tables and information about the firmware, 
and tell how a user can include firmware calls within programs, thereby allowing 
the user to really have control over the machine. The Apple Hcs Firmware Reference 
provides the most authoritative and comprehensive information available on this 
amazingly versatile computer. 



Apple Computer, Inc. 

20525 Mariani Awnue 
Cupertino, Caflfcrnra 95014 

1 I08)5%-Ju"jj 

tlx mm 



03O-3121A 
hinted In 115A 



Addison-Wesky Publishing Company , I DC 



ISBN D-EQ1-177MM-7 



